@picked/client 0.0.101-next.2 → 0.0.101

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

@@ -1,255 +0,0 @@
----
-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',
-    },
-  ],
-})
-```
-
-## Register fields on the client
-
-Register fields when you create the Picked client. Pass a `fields` object. The key of an
-entry becomes the field `key` when the definition does not set one. A definition with its
-own `key` keeps it. Pass a function to build a definition once during the client setup:
-
-```ts
-import { createClient } from 'picked'
-
-const client = createClient({
-  projectId: 'your-project-id',
-  fields: {
-    email: {
-      id: 'email',
-      name: 'email',
-      label: 'Email Address',
-      type: 'text',
-      multiple: false,
-      required: true,
-    },
-    age: () => ({
-      id: 'age',
-      name: 'age',
-      label: 'Age',
-      type: 'number',
-      multiple: false,
-      required: false,
-    }),
-  },
-})
-```
-
-## 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
-
-A field captures nothing until you permit it. Use a privacy policy to let Picked track
-or store the data of a field:
-
-```ts
-const colourField = createField({
-  id: 'favourite-colour',
-  name: 'favourite-colour',
-  type: 'text',
-  label: 'Favourite colour',
-  multiple: false,
-  required: true,
-  policies: {
-    trackValue: true, // Send the value to analytics.
-    storeValue: true, // Keep the value in browser storage.
-  },
-})
-```
-
-**Privacy policies**:
-
-- `trackValue`: set it to `true` to put the value of the field in your analytics events.
-  At `false`, and when the policy is absent, the events carry the field ID only.
-- `storeValue`: set it to `true` to let the SDK put the value in browser storage. At
-  `false`, and when the policy is absent, the SDK keeps the value out of storage.
-
-Both policies keep the value in the browser by default. A field with no `policies`
-object sends no value to your analytics and writes no value to browser storage. Keep
-the default for sensitive data such as a tax number, a credit card number, or a
-password. That data stays in the browser:
-
-```ts
-const sensitiveField = createField({
-  id: 'ssn',
-  name: 'ssn',
-  type: 'text',
-  label: 'Social Security Number',
-  multiple: false,
-  required: true,
-})
-```
-
-Neither policy stops the flow from the use of the value inside the page. A field that
-captures nothing 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

@@ -1,68 +0,0 @@
----
-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/reference/sdk/plugins/create-experience.md

@@ -1,123 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Create Experience Plugin
-
-This plugin registers an array of experiences on the Picked client.
-
-## Define a step
-
-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 the steps on their own.
-const welcomeStep = createStep({
-  id: 'welcome',
-  name: 'Welcome',
-})
-
-const contactStep = createStep({
-  id: 'contact',
-  name: 'Contact Details',
-})
-
-// Define the experience, then add the steps to build the flow.
-const onboardingExperience = createExperience({
-  id: 'onboarding',
-  name: 'User Onboarding',
-  targets: [{ selector: 'body', placement: 'after' }],
-})
-
-onboardingExperience.addStep(welcomeStep)
-onboardingExperience.addStep(contactStep)
-```
-
-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.
-
-You can use the same step on more than one experience.
-
-### Add a field to a step
-
-Define a field with `createField()`.
-
-```ts
-import { createStep, createField } from '@picked/client/plugins/create-experience'
-
-const emailField = createField({
-  id: 'email-address',
-  name: 'email-address',
-  type: 'text',
-  label: 'Email Address',
-  multiple: false,
-  required: true,
-  placeholder: 'you@example.com',
-})
-```
-
-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({
-  id: 'contact',
-  label: 'Contact Details',
-})
-
-contactStep.addField(emailField)
-
-// Or:
-
-const contactStep = createStep({
-  id: 'contact',
-  label: 'Contact Details',
-  fieldIds: [contactStep.id],
-})
-```
-
-## Use a condition in an experience
-
-A [condition](/reference/sdk/conditions) defines when an experience becomes active for the user.
-
-```ts
-import { createExperience, createStep } from '@picked/client/plugins/create-experience'
-
-const productPageFunnel = createExperience({
-  id: 'product-page-funnel',
-  name: 'Product Page Funnel',
-  condition: {
-    and: [
-      {
-        '==': [
-          {
-            var: 'location.pathname',
-          },
-          '/product/:id',
-        ],
-      },
-      {
-        var: 'actions.isSaleActive',
-      },
-    ],
-  },
-  targets: [{ selector: 'body', placement: 'after' }],
-})
-```
-
-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

@@ -1,74 +0,0 @@
----
-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'
-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](/how-to/preview-a-workspace), 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

@@ -1,29 +0,0 @@
----
-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/reference/sdk/plugins/window-object.md

@@ -1,25 +0,0 @@
----
-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/dist/docs/reference/sdk/predicates.md

@@ -1,43 +0,0 @@
----
-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

@@ -1,33 +0,0 @@
----
-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)