@picked/client 0.0.1-dev.1785305085063 → 0.0.1-dev.1785908062293

package/dist/docs/reference/sdk/fields.md

@@ -0,0 +1,209 @@
+---
+type: reference
+layout: docs
+---
+
+# Fields
+
+Define your fields in code with `createField()`. Check the input with JSON Logic.
+Read the values that a user sends through the step context.
+
+## Define a field
+
+Define a field with `createField()` from the
+`@picked/client/plugins/create-experience` package. Each field needs a unique
+identifier, a name, a type, a label, and a count of the values that it takes:
+
+```ts
+import { createField } from '@picked/client/plugins/create-experience'
+
+// A text input that the user must fill in.
+export const emailField = createField({
+  id: 'email-address',
+  name: 'email-address',
+  type: 'text',
+  label: 'Email Address',
+  multiple: false,
+  required: true,
+  placeholder: 'you@example.com',
+})
+
+// A dropdown that takes more than one choice, with fixed options.
+export const communicationMethods = createField({
+  id: 'communication-methods',
+  name: 'communication-methods',
+  type: 'text',
+  label: 'Preferred contact methods',
+  multiple: true,
+  required: true,
+  options: [
+    {
+      id: 'email',
+      label: 'Email',
+      value: 'email',
+    },
+    {
+      id: 'phone',
+      label: 'Phone',
+      value: 'phone',
+    },
+    {
+      id: 'sms',
+      label: 'SMS',
+      value: 'sms',
+    },
+  ],
+})
+```
+
+## Field types
+
+A field has one of four basic types: `text`, `number`, `boolean`, or `object`.
+
+```ts
+// One text input.
+const nameField = createField({
+  type: 'text',
+  multiple: false,
+  // ...
+})
+```
+
+Give an `options` array to let the user choose more than one value:
+
+```ts
+const nameField = createField({
+  type: 'text',
+  multiple: true,
+  options: [
+    {
+      id: 'option-one',
+      label: 'Option One',
+      value: 'product-id-one',
+    },
+    {
+      id: 'option-two',
+      label: 'Option Two',
+      value: 'product-id-two',
+    },
+    {
+      id: 'option-three',
+      label: 'Option Three',
+      value: 'product-id-three',
+    },
+  ],
+})
+```
+
+## Conditions
+
+A field and a field option both work with condition logic:
+
+```ts
+const conditionalField = createField({
+  id: 'conditional-field',
+  type: 'text',
+  condition: {
+    invoke: {
+      var: 'responses.has-answered-question',
+    },
+  },
+  options: [
+    {
+      id: 'conditional-option',
+      label: 'Conditional Label',
+      condition: {
+        invoke: {
+          var: 'responses.eligible-for-option',
+        },
+      },
+    },
+  ],
+})
+```
+
+## Field policies
+
+Use a privacy policy to control how Picked tracks and stores the data of a field:
+
+```ts
+const sensitiveField = createField({
+  id: 'ssn',
+  name: 'ssn',
+  type: 'text',
+  label: 'Social Security Number',
+  multiple: false,
+  required: true,
+  policies: {
+    doNotTrackValue: true, // Do not send the value to analytics.
+    doNotStoreValue: true, // Do not keep the value in browser storage.
+  },
+})
+```
+
+**Privacy policies**:
+
+- `doNotTrackValue`: keeps the value of the field out of your analytics events. The
+  events carry the field ID only.
+- `doNotStoreValue`: stops the SDK, so that it does not put the value in browser
+  storage.
+
+Use these policies for sensitive data such as a tax number, a credit card number, or
+a password. That data must stay in the browser.
+
+Neither policy stops the flow from the use of the value inside the page. A field with both
+policies set still holds its value there, for step validation and for the conditions after
+the step. The policies control what leaves the page: your analytics, and browser
+storage.
+
+## Field metadata
+
+Add more text to help the user:
+
+```ts
+const passwordField = createField({
+  id: 'password',
+  name: 'password',
+  type: 'text',
+  label: 'Password',
+  multiple: false,
+  required: true,
+  placeholder: 'Enter a strong password',
+  description: 'Your password must be at least 8 characters',
+  helpText: 'Use a mix of letters, numbers, and symbols for better security',
+})
+```
+
+**Metadata fields**:
+
+- `placeholder`: the hint text that an empty input shows.
+- `description`: a short explanation below the label.
+- `helpText`: more guidance, or the requirements, next to the field.
+
+## Read a field value
+
+The SDK stores each field response in the experience state. Read a response through
+the `responses` object:
+
+:::code-group
+
+```ts [In Conditions]
+// Point at the value from a later field condition.
+const sensitiveField = createField({
+  condition: {
+    '==': [
+      {
+        var: 'responses.field-name',
+      },
+      'expected-value',
+    ],
+  },
+})
+```
+
+:::
+
+## Related
+
+- [How to validate a field](/how-to/validate-a-field)
+- [Fields](/reference/dashboard/fields) — the dashboard privacy controls.

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

@@ -0,0 +1,68 @@
+---
+type: reference
+layout: docs
+---
+
+# Picked SDK
+
+The Picked SDK lets you add a dynamic, personalized experience to your web
+application with very little code.
+
+:::tip
+The SDK is framework-agnostic. It works with React, Svelte, Vue, and plain
+JavaScript.
+:::
+
+## Precondition and condition
+
+| Category     | Question               | Description                                                                                   |
+| ------------ | ---------------------- | --------------------------------------------------------------------------------------------- |
+| Precondition | Must Picked start?     | Use it to check the environment, to filter by page, or for a feature flag that turns the SDK off completely. |
+| Condition    | Is this user eligible? | Use it to divide your users into groups, to enter a user into an A/B test, or to reach one group of users. |
+
+```ts
+const picked = createClient({
+  precondition: {
+    and: [
+      {
+        or: [
+          {
+            invoke: {
+              var: 'features.aa-test',
+            },
+          },
+          true,
+        ],
+      },
+      { invoke: { var: 'predicates.shopify-is-product-page' } },
+    ],
+  },
+  condition: {
+    invoke: {
+      var: 'features.convincely-enabled',
+    },
+  },
+  // The rest of the Picked options go here.
+})
+```
+
+:::warning
+A precondition or a condition that points at a feature flag reads the bucket of that
+feature flag. That read allocates the visitor at that moment.
+
+A precondition runs at startup. Picked therefore allocates every visitor to a feature
+flag that a precondition points at, before anything else happens. This includes a
+visitor who never reaches the experience that the feature flag controls.
+
+See [Allocation and exposure](/explanation/feature-flag-allocation) before you point a
+precondition at a flag.
+:::
+
+See [conditions](/reference/sdk/conditions) for more detail.
+
+## Related
+
+- [How to install the SDK](/how-to/install-the-sdk)
+- [How to register a component](/how-to/register-a-component)
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  what the difference is between a precondition and a condition.

package/dist/docs/{sdk → reference/sdk}/plugins/create-experience.md

@@ -1,39 +1,21 @@
 ---
+type: reference
 layout: docs
 ---
 
 # Create Experience Plugin
 
-A plugin to register an array of experiences to the Picked client.
+This plugin registers an array of experiences on the Picked client.
 
-## Setup Plugin
+## Define a step
 
-:::code-group
-
-```ts [app.ts]
-import { createClient } from '@picked/client'
-import { createExperiencePlugin } from '@picked/client/plugins/create-experience'
-import { funnelExperience } from '../experiences/funnel-experience'
-import { widgetExperience } from '../experiences/widget-experience'
-
-const client = createClient({
-  projectId: 'your-project-id',
-  plugins: createExperiencePlugin({
-    experiences: [funnelExperience, widgetExperience],
-  }),
-})
-```
-
-:::
-
-## Defining Steps
-
-Steps are defined using `createStep()`. They are added directly to an experience using `experience.addStep()`.
+Define a step with `createStep()`. Add it directly to an experience with
+`experience.addStep()`.
 
 ```ts
 import { createExperience, createStep } from '@picked/client/plugins/create-experience'
 
-// Define standalone steps
+// Define the steps on their own.
 const welcomeStep = createStep({
   id: 'welcome',
   name: 'Welcome',
@@ -44,7 +26,7 @@ const contactStep = createStep({
   name: 'Contact Details',
 })
 
-// Define the experience and add steps to build the flow
+// Define the experience, then add the steps to build the flow.
 const onboardingExperience = createExperience({
   id: 'onboarding',
   name: 'User Onboarding',
@@ -55,13 +37,14 @@ onboardingExperience.addStep(welcomeStep)
 onboardingExperience.addStep(contactStep)
 ```
 
-Each step requires a `name` that identifies it in analytics events. An `id` is optional — one will be generated automatically if omitted.
+Each step needs a `name`, and your analytics events use that name to identify the
+step. An `id` is optional. Picked makes one for you when you give none.
 
-Steps can be used on multiple experiences.
+You can use the same step on more than one experience.
 
-### Adding Fields to Steps
+### Add a field to a step
 
-Fields are defined with `createField()`.
+Define a field with `createField()`.
 
 ```ts
 import { createStep, createField } from '@picked/client/plugins/create-experience'
@@ -77,7 +60,8 @@ const emailField = createField({
 })
 ```
 
-Fields are added to a step with `step.addField()`, or an array of `fieldIds` when creating a step:
+Add a field to a step with `step.addField()`. You can also pass an array of
+`fieldIds` when you create the step:
 
 ```ts
 const contactStep = createStep({
@@ -87,7 +71,7 @@ const contactStep = createStep({
 
 contactStep.addField(emailField)
 
-//Or
+// Or:
 
 const contactStep = createStep({
   id: 'contact',
@@ -96,9 +80,9 @@ const contactStep = createStep({
 })
 ```
 
-## Using conditions in an experience
+## Use a condition in an experience
 
-[Conditions](../conditions) are used to define when an experience will become active for the user.
+A [condition](/reference/sdk/conditions) defines when an experience becomes active for the user.
 
 ```ts
 import { createExperience, createStep } from '@picked/client/plugins/create-experience'
@@ -125,8 +109,15 @@ const productPageFunnel = createExperience({
 })
 ```
 
-Navigation between steps is handled with [conditions](../conditions). Use the `create`
+A [condition](/reference/sdk/conditions) also controls the move from one step to the next.
 
 ```ts
 import { createExperience, createStep } from '@picked/client/plugins/create-experience'
 ```
+
+## Related
+
+- [Plugins](/reference/sdk/plugins)
+- [SDK experiences](/reference/sdk/experiences)
+- [Dynamic Experiences](/reference/sdk/plugins/dynamic-experiences) — the dashboard-driven
+  alternative.

package/dist/docs/reference/sdk/plugins/dynamic-experiences.md

@@ -0,0 +1,74 @@
+---
+type: reference
+layout: docs
+---
+
+# Dynamic Experiences Plugin
+
+This plugin reads the configuration of your project from the Picked API at runtime. You can
+therefore control your experiences, feature flags, steps, fields, and conditions from
+the [dashboard](/reference/dashboard/experiences) alone.
+
+The plugin reads the configuration of your project and the CMS content of your
+experiences from one source. It does not mix them. Picked gives a configuration and its
+content the same version.
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `'bundle' \| 'api'` | see below | Where to read the configuration and the content from. |
+| `apiUrl` | `string` | `https://api.picked.app` | Your own API URL, for a self-hosted or local API. |
+| `projectConfig` | `ProjectConfig` | none | A configuration that you give. The plugin makes no request for it. |
+| `getContent` | `function` | none | A function that you give. The plugin calls it for each experience that uses CMS content. |
+
+### mode
+
+| Value | Source | Use it when |
+| --- | --- | --- |
+| `'bundle'` | The data that the [Vite plugin](/reference/tools/vite-plugin) puts in your build | You want no API request when the page loads. |
+| `'api'` | The Picked API, read when the client starts | You want a workspace publish to reach users without a new deployment. |
+
+:::code-group
+
+```ts [app.ts]
+import { createClient } from '@picked/client'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [dynamicExperiencesPlugin({ mode: 'bundle' })],
+})
+
+client.start()
+```
+
+:::
+
+If you do not set `mode`, the plugin uses the build data when the Vite plugin gave it
+some. In every other case it uses the API.
+
+### projectConfig and getContent
+
+These two replace the source for you. Keep the configuration and the content at the same
+version when you use them. The plugin cannot make that check for you.
+
+## Preview mode
+
+After you [enter preview mode from the dashboard](/reference/dashboard/workspaces#preview), the SDK
+receives a preview token and starts preview mode:
+
+- The plugin reads fresh options from the API with that token, for any value of `mode`.
+  It does not read the build-time configuration, a `projectConfig` that you give, or the
+  cached options.
+- A feature flag decision uses session storage. The decision resets when you close
+  the tab.
+
+A `getContent` function keeps its place in a preview session, and it receives the token.
+You therefore decide what a preview means for your own content.
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works) — how the plugin resolves your
+  options at startup.
+- [About feature flag allocation](/explanation/feature-flag-allocation)

package/dist/docs/reference/sdk/plugins/index.md

@@ -0,0 +1,29 @@
+---
+type: reference
+layout: docs
+---
+
+# Plugins
+
+A plugin adds behaviour to the Picked client. Pass one to the `plugins` array of
+`createClient()`.
+
+| Plugin | Import | What it does |
+| --- | --- | --- |
+| [Dynamic Experiences](/reference/sdk/plugins/dynamic-experiences) | `@picked/client/plugins/dynamic-experiences` | Reads the published configuration of your project at runtime and registers every experience, step, field, condition, and feature flag. |
+| [Create Experience](/reference/sdk/plugins/create-experience) | `@picked/client/plugins/create-experience` | Registers an experience, a step, and a field that you define in code. |
+| [Window Object](/reference/sdk/plugins/window-object) | `@picked/client/plugins/window-object` | Puts the client on `window.Picked`, which helps when you debug. |
+| Single Page App | `@picked/client/plugins/single-page-app` | Starts the client again on a history event. |
+| React framework | `@picked/react/plugins/framework` | Lets the client render a React component. |
+| Svelte framework | `@picked/svelte/plugins/framework` | Lets the client render a Svelte component. |
+| Devtools | `@picked/svelte/plugins/devtools` | Connects the client to the Chrome extension. |
+
+Most applications need a framework plugin and **one** of Dynamic Experiences or Create
+Experience. Dynamic Experiences puts your options in the dashboard; Create Experience
+puts them in code.
+
+## Related
+
+- [How to install the SDK](/how-to/install-the-sdk) — where the plugins go.
+- [SDK installation](/reference/sdk) — every client option.
+- [How to debug with the Chrome extension](/how-to/debug-with-the-chrome-extension)

package/dist/docs/{sdk → reference/sdk}/plugins/window-object.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -17,3 +18,8 @@ const client = createClient({
   plugins: [windowObjectPlugin()],
 })
 ```
+
+## Related
+
+- [Plugins](/reference/sdk/plugins)
+- [How to install the SDK](/how-to/install-the-sdk)

package/dist/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/dist/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/dist/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)