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

package/dist/docs/how-to/upload-and-use-an-asset.mdx

@@ -0,0 +1,73 @@
+---
+type: how-to
+layout: docs
+---
+
+import { Screenshot } from '../../../components/Screenshot'
+
+# How to upload and use an asset
+
+This guide shows you how to put a file in the asset library and point at it from your
+content.
+
+## 1. Add the field to a layout
+
+Two field types point at the library:
+
+- An **Asset** field takes an image, a video, or a document.
+- An **HTML** field takes a `.html` file.
+
+Add one of them to a page layout or a step layout.
+
+## 2. Choose a file
+
+1. Open the content entry.
+2. Click **Choose file** on the asset field. On a field that holds a value already, click
+   **Replace**.
+3. Open the **Upload** tab to add a new file.
+4. Open the **Library** tab to use a file that is there already.
+5. Choose your asset.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/design-systems/new"
+  wait='button:has-text("Upload file")'
+  click='button:has-text("Upload file")'
+  selector="[role=dialog]"
+  alt="The asset picker modal on the Picked dashboard, with the Library tab, its search box, its type filter, and its Sort menu"
+  renderWidth={1072}
+  renderHeight={790}
+/>
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/design-systems/new"
+  wait='button:has-text("Upload file")'
+  click='button:has-text("Upload file")'
+  selector="[role=dialog]"
+  alt="The asset picker modal on the Picked dashboard, with the Library tab, its search box, its type filter, and its Sort menu"
+  renderWidth={1072}
+  renderHeight={790}
+/>
+
+The detail panel on the right shows the kind, the dimensions, the size, and the upload
+date.
+
+## 3. Find an asset in a large library
+
+The **Library** tab has three controls, and the server applies each one across the whole
+library:
+
+- **Search by name** narrows the list by file name while you type.
+- The type filter narrows the list to one media type. **All types** is the default.
+- **Sort** orders the list by **Name**, **Date created**, or **Date updated**.
+
+Click **Load more** at the bottom to read the next page of results.
+
+:::tip
+Each row has an **Open in new tab** control. Use it to check an asset again before you
+choose it. Your choice in the picker stays as it is.
+:::
+
+## Related
+
+- [Asset library](/reference/dashboard/content/asset-library) — the limits, the file
+  types, and how Picked serves an uploaded file.

package/dist/docs/how-to/validate-a-field.md

@@ -0,0 +1,52 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to validate a field
+
+This guide shows you how to check what a visitor enters. Write the rule in JSON Logic. The
+`$input` variable holds the current value of the field.
+
+## Steps
+
+Add a `validation` rule to `createField()`:
+
+```ts
+import { createField } from '@picked/client/plugins/create-experience'
+
+const quantityField = createField({
+  id: 'quantity',
+  name: 'quantity',
+  type: 'number',
+  label: 'Quantity',
+  multiple: false,
+  required: true,
+  validation: {
+    catch: {
+      or: [
+        {
+          and: [
+            { '>': [{ var: '$input' }, 0] },
+            { '<=': [{ var: '$input' }, 999] },
+          ],
+        },
+        { throw: 'Please enter a value between 1 and 999' },
+      ],
+    },
+  },
+})
+```
+
+:::tip
+The `catch` and `throw` pattern checks that the condition gives `true`. When it does not,
+the SDK shows the `throw` message to your visitor.
+:::
+
+The SDK runs the rule on blur and on submit.
+
+## Related
+
+- [SDK fields](/reference/sdk/fields) — every field option.
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  the rule format.

package/dist/docs/how-to/write-a-condition.md

@@ -0,0 +1,45 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to write a condition
+
+This guide shows you how to build a rule in the visual condition builder. The builder
+appears on a condition node, on an experience condition, on an initialize-open condition,
+and on a field option.
+
+## Steps
+
+1. Choose the node or the field that takes the condition.
+2. Find the **Logic** section in the inspector.
+3. Choose a data source: **Responses**, **Actions**, **Feature flags**, **Conditions**,
+   or **Window Location**.
+4. Choose an operator. The choices include equals, not equals, greater than, and
+   contains.
+5. Enter a value.
+
+## Join more than one rule
+
+1. Create an AND group or an OR group.
+2. Add your rules inside it.
+
+With **AND** every rule must match. With **OR** one rule must match. Put a group inside
+another group to build a larger rule.
+
+## Example
+
+To show a step only to a visitor who is on one page and who accepted marketing:
+
+1. Create an AND group.
+2. Add a rule: **Window Location → pathname** equals `/pricing`.
+3. Add a rule: **Responses → `marketing_opt_in`** equals `true`.
+
+The group matches only when both rules are true.
+
+## Related
+
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  what a rule can read.
+- [Condition builder](/reference/dashboard/flow-builder/condition-builder) — the rule
+  structure.

package/dist/docs/how-to/write-a-predicate.md

@@ -0,0 +1,60 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to write a predicate
+
+This guide shows you how to let a condition read data that only your application holds,
+such as a cart total or an account level.
+
+## 1. Define the predicate
+
+Pass a `predicates` object to `createClient()`:
+
+```ts
+import { createClient } from '@picked/client'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  predicates: {
+    'is-example-page': ({ location }) => location?.pathname === '/example',
+    'get-account-tier': async () => {
+      const data = await fetch('/api/get-account-tier').then((r) => r.json())
+      return data.result
+    },
+  },
+})
+```
+
+A predicate returns a boolean, a string, an array of strings, or `undefined`. It can also
+return a promise that resolves to one of those.
+
+## 2. Invoke it from a condition
+
+```ts
+condition: {
+  '==': [
+    { invoke: { var: 'predicates.is-example-page' } },
+    true,
+  ],
+}
+```
+
+:::tip
+A predicate also works inside `validation` logic.
+:::
+
+## Keep it pure and fast
+
+- The same snapshot must always give the same result.
+- Check that a response or a field is there before you read its value. Return `undefined`
+  when the data is not available, and do not throw.
+- The SDK can invoke a predicate many times, so keep the logic small.
+- Do not change the snapshot. It is frozen, and a change to it throws in strict mode.
+
+## Related
+
+- [Predicates](/reference/sdk/predicates) — the state snapshot shape.
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  why predicates exist.

package/dist/docs/index.md

@@ -1,77 +1,59 @@
 ---
+type: map
 layout: docs
 ---
 
-# Getting Started
+# Picked documentation
 
-Picked lets you build personalized UI flows in a visual editor and deliver them to visitors on your site with a lightweight SDK.
+Picked lets you build personalized UI flows in a visual editor. The SDK then serves them
+to the visitors on your site.
 
-## How it works
+There are two paths to follow. Choose the one that matches your work.
 
-You design experiences in the dashboard using a drag-and-drop flow builder. The SDK fetches your published experiences and renders them on your site.
+## Work in the dashboard
 
-## Quick start
+Build experiences, write content, and publish.
 
-### 1. Create a project
+Start with [build your first experience](/tutorials/first-experience-in-the-dashboard).
+It takes you from an empty project to a survey on your own site, and it needs no
+development tools.
 
-Sign in to the dashboard and create a project. A project represents one website or app.
+One thing must happen first: a developer adds the Picked SDK to your site one time. After
+that, the dashboard is all you need.
 
-See [Projects](/projects) for details.
+Then:
 
-### 2. Install the SDK
+- **[Build](/how-to/create-an-experience)** — experiences, flows, conditions, and A/B
+  tests.
+- **[Content](/how-to/define-a-page-layout)** — layouts, sections, pages, and assets.
+- **[Publish](/how-to/publish-a-workspace)** — preview, publish, and roll back.
+- **[Administer and measure](/how-to/invite-and-remove-members)** — members, API keys,
+  analytics, and the tools that connect Picked to Google Tag Manager and to an AI tool.
+- **[Dashboard reference](/reference/dashboard/projects)** — every dashboard screen and
+  every option, plus the [glossary](/reference/glossary).
+- **[How Picked works](/explanation/how-picked-works)** — what happens when you publish.
 
-Add the SDK to your site and initialize the client. Copy the snippet from your project home page.
+## Integrate with code
 
-```typescript
-import { createClient } from '@picked/client'
+Add Picked to a site or an application. Your code then renders the experiences that the
+dashboard describes.
 
-const picked = createClient({
-  projectId: 'your-project-id',
-  plugins: [],
-})
+Start with [add Picked to your application](/tutorials/first-experience). It goes from an
+empty project to a survey that runs in React or in Svelte.
 
-picked.start()
-```
+Read the dashboard documents above also. Everything your code renders is described
+there, so the two paths link to each other rather than repeat.
 
-See [SDK Installation](/sdk) for full setup options.
+Then:
 
-### 3. Register a component
-
-Register components when creating the client. Each key in the `components` object must match a component name you set in the dashboard.
-
-```typescript
-import { createClient } from '@picked/client'
-
-const picked = createClient({
-  projectId: 'your-project-id',
-  components: {
-    'welcome-survey': YourComponent,
-  },
-})
-
-picked.start()
-```
-
-See [SDK Experiences](/sdk/experiences) for targeting, conditions, and component adapters.
-
-### 4. Create an experience
-
-In the dashboard, open your project and click **Experiences** > **New Experience**. Enter a name and set the component name to match your registered component (e.g., `welcome-survey`).
-
-See [Experiences](/experiences) for configuration options.
-
-### 5. Build the flow
-
-Open the flow builder and drag steps, actions, and conditions onto the canvas. Connect nodes to define the visitor's path through the experience.
-
-See [Flow Builder](/flow-builder/overview) for a full walkthrough.
-
-### 6. Save and publish
-
-Click **Save** in the flow builder toolbar. The SDK picks up the published experience and renders it to matching visitors on your site.
-
-## Next steps
-
-- [Flow Builder](/flow-builder/overview) — Build experience flows visually
-- [Steps](/steps), [Fields](/fields), [Actions](/actions), [Conditions](/conditions) — Configure the building blocks of experiences
-- [SDK Installation](/sdk) — Full SDK setup and configuration
+- **[Integrate the SDK](/how-to/install-the-sdk)** — install, register a component, read
+  a feature flag.
+- **[Build a step form](/how-to/render-a-step-form)** — render fields, act on a
+  submission, validate input.
+- **[Server-side rendering](/how-to/server-render-a-page)** — a page that a search engine
+  can read.
+- **[Authenticate](/how-to/authenticate-with-a-password)** — the management API.
+- **[SDK reference](/reference/sdk)**, **[Delivery API](/reference/delivery-api)**,
+  **[PickedQL](/reference/pickedql)**.
+- **[Why it works this way](/explanation/why-server-side-rendering)** — the design
+  behind the SDK.

package/dist/docs/reference/dashboard/actions.mdx

@@ -0,0 +1,53 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Actions
+
+An action is a side effect that starts when the flow reaches it. Use an action to
+track an event, to send data to an external service, or to call a webhook.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/actions"
+  alt="The actions list for a workspace on the Picked dashboard"
+/>
+
+## Set up an action
+
+**Name**: The name that the dashboard shows. Your visitors do not see it.
+
+**Key**: The identifier that your application uses for this action. Your visitors do
+not see it.
+
+## Register in your application
+
+Each action key must match a key in the `actions` object that you pass to
+`createClient()`. See
+[How to register an action handler](/how-to/register-an-action-handler) for the code, and
+[SDK actions](/reference/sdk/actions) for what the handler receives and returns.
+
+## Use actions in flows
+
+In the flow builder, drag an action from the library onto the canvas. Connect it to
+the point in the flow where you want it to start.
+
+An action runs when the flow reaches its node. It does not interrupt your visitor. By
+default the flow continues to the next connected node.
+
+An action node can carry a **success** branch and a **failure** branch. Which one the flow
+takes depends on whether your handler throws, and a returned `false` is a success. See
+[How an action decides which way to go](/explanation/how-picked-works#how-an-action-decides-which-way-to-go).
+
+## Reuse actions
+
+An action belongs to the project. Use the same action in more than one experience flow.
+A change to the options of an action applies at every place that uses it.
+
+## Related
+
+- [How to add a step, a field, an action, or a condition](/how-to/add-a-step-field-or-action)
+- [How to register an action handler](/how-to/register-an-action-handler)
+- [SDK actions](/reference/sdk/actions) — what the handler receives and returns.

package/dist/docs/reference/dashboard/api-keys.mdx

@@ -0,0 +1,37 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# API keys
+
+An API key lets your code reach the Picked API. Use one for a server-side integration
+or for a CI/CD workflow.
+
+<Screenshot
+  route="/{orgSlug}/api-keys"
+  alt="The API keys list for an organization on the Picked dashboard"
+/>
+
+## Use an API key
+
+Put your API key in the `Authorization` header of each request to the
+[Picked API](/tutorials/first-api-call).
+
+```
+Authorization: Bearer your-api-key
+```
+
+## Scopes
+
+An API key carries scopes, and the scopes limit what the key can reach. Choose the
+scopes that your integration needs when you create the key. A key can do only the
+operations that its scopes permit.
+
+## Related
+
+- [How to create and revoke an API key](/how-to/create-and-revoke-an-api-key)
+- [How to authenticate with an API key](/how-to/authenticate-with-an-api-key) — the API
+  side.

package/dist/docs/reference/dashboard/conditions.mdx

@@ -0,0 +1,42 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Conditions
+
+A condition evaluates a rule and splits the flow into two paths. One path is for a
+true result, the other for a false result.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/conditions"
+  alt="The conditions list for a workspace on the Picked dashboard"
+/>
+
+## Set up a condition
+
+**Name**: The name that the dashboard shows. Your visitors do not see it.
+
+**Key**: The identifier for your application. You set it once and you cannot change
+it. Your visitors do not see it.
+
+## Branches
+
+In the flow builder, a condition node has two output handles. The green handle, for a
+true result, leads to the path for a match. The red handle, for a false result, leads
+to the other path.
+
+You can chain conditions. Connect the output of one condition to the input of another
+to build a decision tree.
+
+## Related
+
+- [How to add a step, a field, an action, or a condition](/how-to/add-a-step-field-or-action)
+
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  what a rule can read.
+- [How to write a condition](/how-to/write-a-condition)
+- [Condition builder](/reference/dashboard/flow-builder/condition-builder) — the data
+  sources and the rule structure.

package/dist/docs/reference/dashboard/content/asset-library.mdx

@@ -0,0 +1,63 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Asset Library
+
+The Asset Library holds the files that your content points at. These are images,
+video, documents, and HTML.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/assets"
+  alt="The asset library on the Picked dashboard"
+/>
+
+## Upload and control your assets
+
+The Asset Library is a project-level store. Upload a file, then point at it from any
+Content Entry in the project.
+
+- **Size limit:** 50 MB for each file.
+- **Allowed types:** an image in PNG, JPEG, WebP, AVIF, GIF, or SVG. A video in MP4
+  or WebM. A common document format. HTML, as `text/html`.
+
+Picked rejects a file of another type. It also rejects a file above the size limit.
+
+## HTML assets
+
+Upload a `.html` file and point at it from an **HTML asset** field. Picked then scans
+the file. The scan is advisory: it helps you, and it never stops you. It
+reports findings about speed, about search rank, and about accessibility, so that you
+can improve the file before you publish it:
+
+- **File size:** a warning at 100 KB, and a stronger one at 250 KB.
+- **Inline images:** a note when inline `base64` image data adds about 50 KB or more.
+- **Image dimensions:** an image with no width and no height. Such an image can move
+  the content around it while the page loads.
+- **Lazy load:** an image with no `loading="lazy"` attribute.
+- **Link safety:** an external link with `target="_blank"` and no `rel="noopener"`.
+- **Link search rank:** an external link with no `rel="nofollow"`.
+- **Accessibility:** a pass by `axe-core`. It covers alt text, heading order,
+  contrast, and more.
+
+Every finding is advisory. You can always upload the file as it is.
+
+## How assets are served
+
+Picked serves each asset from a sandboxed storage origin. That origin is separate
+from the trusted origin of your application. HTML therefore comes from its own
+origin, so a document that you upload runs in isolation and cannot reach the page
+that holds it. A script in that document cannot read a session, a token, or the DOM
+around it, because each of those needs same-origin access.
+
+An [Experience Content](/reference/delivery-api/experience-content) response can hold an HTML
+asset. The response then carries the content of that asset, and the SDK renders it
+with no second request to storage.
+
+## Related
+
+- [How to upload and use an asset](/how-to/upload-and-use-an-asset)
+- [Fields](/reference/dashboard/fields) — the field type for an HTML asset.

package/dist/docs/reference/dashboard/content/content-entries.mdx

@@ -0,0 +1,44 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Content Entries
+
+A Content Entry is an instance of a layout filled with real data. A Page renders one entry; a Flow Step can render one too.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/content"
+  alt="The content entries list on the Picked dashboard"
+/>
+
+## What a content entry is
+
+A Content Entry is an instance of a layout's schema. The [layout](/reference/dashboard/content/layouts) defines the fields; the entry holds the actual values. One layout can back many entries, each with its own data.
+
+## How entries bind to pages and steps
+
+A [Page](/reference/dashboard/content/pages) has a single Step, and that Step links to its entry through the layout content link. A Flow [Step](/reference/dashboard/steps) backed by a Step Layout binds an entry the same way. When the SDK renders the Page or Step, it resolves the linked entry and hands its data to your component.
+
+## Edit entry data
+
+The entry editor renders a form from the layout schema. There is one input for each
+field, in the order that the schema sets. A repeatable field appears as a sortable
+list. You can add to that list and put it into a new order. A group field holds its
+inputs under one heading.
+
+## Validation
+
+Invalid data appears as an error on each field. The error carries a path in the JSON
+style, and it points at the exact place in the entry, for example
+`sections[0].data.title`. Fix every error before you publish, because Picked serves
+valid content only.
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why the schema and the data
+  are separate.
+- [How to fill and publish a page](/how-to/fill-and-publish-a-page)
+- [Page and step layouts](/reference/dashboard/content/layouts)

package/dist/docs/reference/dashboard/content/layouts.mdx

@@ -0,0 +1,62 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Page & Step Layouts
+
+Layouts are reusable JSON schemas. Page Layouts back standalone Pages; Step Layouts back individual Steps inside a Flow.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/models"
+  alt="The layouts list in the schema builder on the Picked dashboard"
+/>
+
+## A page layout and a step layout
+
+Each layout has a fixed category, and the category decides what the layout gives its
+shape to:
+
+| Layout | It gives its shape to | Who renders it |
+| --- | --- | --- |
+| **Page Layout** | A standalone [Page](/reference/dashboard/content/pages). | The SDK renders the entry on your server. |
+| **Step Layout** | One [Step](/reference/dashboard/steps) inside a Flow. | The Step renders the entry in the browser. |
+
+## Field types
+
+A layout is built from fields. Each field has a type that decides its editor and the shape of the value it stores.
+
+| Type | Stores | Use it for |
+| --- | --- | --- |
+| **Single-line text** | A short string. | A title, a label, or a short headline. |
+| **Multi-line text** | A longer plain string. | A description, or a paragraph with no format marks. |
+| **Markdown** | A Markdown string. | Body copy with format marks. |
+| **Slug** | A URL-safe string. | A part of a path, or an identifier. |
+| **Number** | A numeric value. | A price, a count, or a rating. |
+| **Boolean** | A true or false value. | A toggle or a flag. |
+| **Date** | A date value. | A publish date or a deadline. |
+| **Color** | A color value. | A theme accent or a swatch. |
+| **JSON** | Any JSON value. | Structured data with no editor of its own. |
+| **Group** | An object of fields inside the layout. | A set of related fields, held together. |
+| **Section** | A [Section](/reference/dashboard/content/sections) schema inside the layout. | A shared schema fragment that you reuse. |
+| **Asset** | A link to an [Asset Library](/reference/dashboard/content/asset-library) item. | An image, a video, or a document. |
+| **HTML asset** | A link to a `.html` file in your library. | HTML that you wrote before, held inside the content. |
+
+## Repeatable and grouped fields
+
+You can make any field **repeatable**. It then renders as a sortable list of values,
+and not as one value. Use it for a gallery, for a list of features, or for any
+collection.
+
+A **Group** field holds a set of fields under one key, and it gives a structured
+object. Make a group repeatable to describe a list of objects, such as a list of
+feature cards.
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why a schema change does not
+  migrate your data.
+- [How to define a page layout](/how-to/define-a-page-layout)
+- [How to reuse a section](/how-to/reuse-a-section)