@picked/client 0.0.101-next.1 → 0.0.101-next.3

package/dist/docs/how-to/install-the-sdk.md

@@ -1,93 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to install the SDK
-
-This guide shows you how to add the Picked client to a web application. You need a project
-ID from the dashboard.
-
-## 1. Install the packages
-
-:::code-group
-
-```bash [React]
-npm install picked @picked/react
-```
-
-```bash [Svelte]
-npm install picked @picked/svelte
-```
-
-:::
-
-`picked` gives you the client, the `picked.config` helpers, and the `picked` command. Your
-package manager adds `@picked/client` with it, which carries the runtime and holds the
-generated types.
-
-## 2. Add `picked.config.ts`
-
-Create this file in the root of your project. The `picked` command and the
-[Vite plugin](/reference/tools/vite-plugin) read your project identity from it:
-
-```typescript
-import { defineConfig } from 'picked/config'
-
-export default defineConfig({
-  projectId: 'your-project-id',
-})
-```
-
-[Type generation](/reference/sdk/type-generation) reads this file, and gives your fields,
-features and steps the types the workspace declares.
-
-## 3. Create and start the client
-
-:::code-group
-
-```tsx [React]
-import { createClient } from 'picked'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
-
-export const picked = createClient({
-  projectId: 'your-project-id',
-  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-})
-
-picked.start()
-```
-
-```ts [Svelte]
-import { createClient } from 'picked'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
-
-export const picked = createClient({
-  projectId: 'your-project-id',
-  plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-})
-
-picked.start()
-```
-
-:::
-
-`picked` carries the client's root entry. Each deeper import path, such as
-`@picked/client/plugins/dynamic-experiences` and `@picked/client/server`, keeps its own
-name.
-
-`start()` is idempotent. A second call changes nothing on a client that started already.
-
-## 4. Add the optional plugins
-
-- `windowObjectPlugin()` puts the client on `window.Picked`, which helps when you debug.
-- `singlePageAppPlugin()` starts the client again on a history event.
-
-## Related
-
-- [Add Picked to your application](/tutorials/first-experience) — the whole path.
-- [SDK installation](/reference/sdk) — every client option.
-- [Type generation](/reference/sdk/type-generation) — types from your workspace.
-- [How to register a component](/how-to/register-a-component).

package/dist/docs/how-to/install-the-vite-plugin.md

@@ -1,69 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to install the Vite plugin
-
-This guide shows you how to embed your project configuration at build time, so the SDK makes no
-API request at runtime.
-
-## 1. Install
-
-:::code-group
-
-```bash [npm]
-npm install @picked/vite-plugin-picked picked
-```
-
-```bash [pnpm]
-pnpm add @picked/vite-plugin-picked picked
-```
-
-```bash [yarn]
-yarn add @picked/vite-plugin-picked picked
-```
-
-:::
-
-## 2. Name your project
-
-Create `picked.config.ts` in the root of your project. The plugin reads your project
-identity from this file:
-
-```typescript
-import { defineConfig } from 'picked/config'
-
-export default defineConfig({
-  projectId: 'your-project-id',
-})
-```
-
-## 3. Add the plugin to your Vite config
-
-```typescript
-import { defineConfig } from 'vite'
-import { picked } from '@picked/vite-plugin-picked'
-
-export default defineConfig({
-  plugins: [picked()],
-})
-```
-
-When Vite starts, the plugin reads your project configuration and embeds them in your bundle.
-The SDK then reads the embedded configuration and makes no network request.
-
-The plugin also writes `picked-env.d.ts`, which types your fields, features and steps
-against the workspace. See [Type generation](/reference/sdk/type-generation).
-
-:::note
-When a preview token is there at runtime, the SDK ignores the embedded configuration and reads
-fresh data from the API.
-:::
-
-## Related
-
-- [Vite plugin](/reference/tools/vite-plugin) — every option.
-- [Type generation](/reference/sdk/type-generation) — the `picked.config.ts` options.
-- [About how Picked works](/explanation/how-picked-works) — where build-time configuration sit
-  in the startup order.

package/dist/docs/how-to/invite-and-remove-members.md

@@ -1,35 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to invite and remove members
-
-This guide shows you how to control who reaches your organization.
-
-## Invite a member
-
-1. Open your organization.
-2. Click **Members**.
-3. Click **Invite member**.
-4. Enter an email address.
-5. Choose a role. Give the smallest role that the work needs.
-6. Click **Send invitation**.
-
-The person receives an email with a link to join. To join, they click the link in the
-email and set a password. They can also go to the register page and enter the same email
-address. Then they confirm the address and set a password.
-
-## Remove a member
-
-1. Open your organization.
-2. Click **Members**.
-3. Find the member.
-4. Click **Remove** next to the name.
-5. Confirm.
-
-The member loses access to every project in the organization immediately.
-
-## Related
-
-- [Team management](/reference/dashboard/team-management) — the roles.

package/dist/docs/how-to/point-one-entry-at-another.md

@@ -1,61 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to point one entry at another
-
-This guide shows you how to point one content entry at another, such as a product at its
-category. You need two Models: the one that holds the pointer, and the one that the
-pointer reaches.
-
-## 1. Create the target Model
-
-1. Click **CMS** in the sidebar, then **Models**.
-2. Click **New model**.
-3. Enter a **Name** and a **Key**, such as `category`.
-4. Leave **Category** as **None (general content)**.
-5. Add your fields.
-6. Click **Create model**.
-
-## 2. Add a Reference field
-
-1. Open the Model that holds the pointer.
-2. Drag a **Reference** property onto the schema.
-3. Enter a **Name** and a **Key**, such as `category`.
-4. Set **Target Model** to the Model from step 1.
-5. Click **Save**.
-
-Turn on **repeatable** for a field that points at more than one entry. Leave **Target
-Model** as **Any Model** to accept an entry of any Model in the workspace.
-
-## 3. Choose a target on an entry
-
-1. Open a content entry that uses the Model.
-2. Find your Reference field.
-3. Click **Choose entry**.
-4. Search for the entry.
-5. Choose the entry.
-6. Click **Save**.
-
-Use **Change entry** to point the field somewhere else. Use **Clear** to remove the
-pointer. **Clear** deletes no content.
-
-## Delete a target
-
-Picked does not delete an entry while another entry points at it. Clear the reference on
-each entry that points at the target, then delete the target.
-
-The same rule holds for a Model. Remove the Reference field that holds it as its **Target
-Model** first.
-
-## Read it in your code
-
-The pointer and the entry travel separately. See
-[How to read a referenced entry](/how-to/read-a-referenced-entry).
-
-## Related
-
-- [About content references](/explanation/content-references) — why a reference is a pointer.
-- [Models](/reference/dashboard/content/models) — the field and its options.
-- [Content entries](/reference/dashboard/content/content-entries) — the editor reference.

package/dist/docs/how-to/preview-a-workspace.md

@@ -1,28 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to see a preview of a workspace
-
-This guide shows you how to see an unpublished change on your own site before your
-visitors get it. You need a draft workspace with at least one change in it.
-
-## Steps
-
-1. Click **Preview** in the workspace toolbar.
-2. Enter the URL of your site.
-3. Set each feature flag to the **Default** value, to **On**, or to **Off**. This step
-   is optional.
-4. Click **Open preview**.
-
-Your site opens in a new tab with the unpublished workspace applied.
-
-The preview sends the workspace state to the SDK in the query parameters. The visitors on
-your live site therefore see no change.
-
-## Related
-
-- [About workspaces and versions](/explanation/workspaces-and-versions) — why a preview
-  cannot reach production.
-- [Workspaces](/reference/dashboard/workspaces) — the workspace states.

package/dist/docs/how-to/publish-a-workspace.md

@@ -1,30 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to publish a workspace
-
-This guide shows you how to make the changes in a workspace live. You need a draft
-workspace with at least one unpublished change.
-
-The **Publish** button is active only when the workspace holds an unpublished change. A
-badge in the toolbar shows the current state.
-
-## Steps
-
-1. Click **Publish** in the workspace toolbar.
-2. Read the change preview in the publish modal.
-3. Expand any modified row to see which properties changed.
-4. Read the banner above the diff, if one is there. It reports a change that breaks
-   another record.
-5. Click **Publish** to confirm.
-
-Picked makes an immutable snapshot of your workspace, and the SDK serves it to your
-visitors.
-
-## Related
-
-- [About workspaces and versions](/explanation/workspaces-and-versions) — why the modal
-  shows a diff.
-- [How to roll back a published version](/how-to/roll-back-a-published-version).

package/dist/docs/how-to/read-a-feature-flag.md

@@ -1,113 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to read a feature flag
-
-This guide shows you how to read the resolved bucket of a feature flag in your
-application. You need a feature flag in your project first, either from the dashboard or
-[defined in SDK code](/reference/sdk/features#define-a-feature-flag-in-sdk-code).
-
-Which accessor you pick decides *when* the visitor enters the test, so read
-[About feature flag allocation](/explanation/feature-flag-allocation) before you choose.
-
-## 1. Choose an accessor
-
-Each accessor returns a different value, and they differ in whether a read resolves the
-feature flag. A read that resolves the feature flag commits the visitor to a bucket and reports the
-decision.
-
-| API | Returns | Does a read resolve the feature flag? |
-| --- | --- | --- |
-| `useFeature` / `getFeature` | `() => Promise<bucket>` | Only when you call the function that it returns |
-| `useFeatureResult` / `getFeatureResult` | `{ id, bucket }`, and `undefined` until it resolves | Yes, as soon as the component renders |
-| `useFeatureEnabled` / `getFeatureEnabled` | `boolean \| undefined`, the dashboard **Enabled** setting | No |
-| `client.features.listStore` | Every registered feature flag, each with an `isResolved` property | No |
-| `client.features.getById(id)` | A store that holds one feature flag | No |
-
-Some decisions must wait for data that you do not have yet, such as a cart, a quote, or
-the profile of a signed-in user. For those, use `useFeature` or `getFeature`. Call the
-function they return after the data arrives.
-
-## 2. Read the bucket
-
-The bucket is what your site receives. A Boolean feature flag gives `true` or `false`. A
-Text feature flag gives the value of one variant, or `false` for the control group.
-
-:::code-group
-
-```tsx [React]
-import { useFeatureResult } from '@picked/react/hooks'
-
-function MyComponent() {
-  // { id, bucket }, or undefined until the feature flag resolves.
-  const result = useFeatureResult('hero')
-
-  return (
-    <div>
-      {result?.bucket === false && <p>Control</p>}
-      {result?.bucket === 'hero-a' && <p>Hero A</p>}
-      {result?.bucket === 'hero-b' && <p>Hero B</p>}
-    </div>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getFeatureResult } from '@picked/svelte/hooks'
-
-  // A store that holds { id, bucket }, or undefined until the feature flag resolves.
-  const result = getFeatureResult('hero')
-</script>
-
-{#if $result?.bucket === false}
-  <p>Control</p>
-{:else if $result?.bucket === 'hero-a'}
-  <p>Hero A</p>
-{:else if $result?.bucket === 'hero-b'}
-  <p>Hero B</p>
-{/if}
-```
-
-:::
-
-:::warning
-`useFeatureResult` and `getFeatureResult` resolve the feature flag as soon as the component
-renders, and they commit the visitor to a bucket at that moment.
-:::
-
-:::tip
-Run [type generation](/reference/sdk/type-generation) and `bucket` narrows to the values
-that this Text feature flag declares. Your editor then shows each value, and it reports a
-comparison against a value that the feature flag cannot serve.
-:::
-
-## 3. Read it without a framework
-
-The event bus works with any framework, and with none:
-
-```ts
-import { createClient } from 'picked'
-
-const client = createClient({
-  /* Put your client options here. */
-})
-
-client.eventBus.watch((event) => {
-  if (event.type === 'feature_decide' && event.feature.id === 'my-feature') {
-    console.log(event.feature) // { id: 'my-feature', key: 'v1', bucket: 'hero-a' }
-  }
-})
-```
-
-`feature_decide` fires only when the SDK makes a new decision. A visitor who returns
-restores the decision from storage and fires nothing, so watch
-`client.features.listStore` when you need the current state instead.
-
-## Related
-
-- [About feature flag allocation](/explanation/feature-flag-allocation) — when the
-  visitor enters the test.
-- [SDK feature flags](/reference/sdk/features) — the definition shape and the overrides.

package/dist/docs/how-to/read-a-referenced-entry.md

@@ -1,109 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to read a referenced entry
-
-This guide shows you how to read the content that a
-[Reference field](/reference/dashboard/content/models#reference-fields) points at. You
-need a component that renders a step first. See
-[How to render a step form](/how-to/render-a-step-form).
-
-A Reference field holds a pointer, and not the content. The entry travels beside the
-content of the step, so you resolve the pointer against the content of the client.
-
-## 1. Resolve a single reference
-
-Pass the raw field value to `useReference()` in React, or to `getReference()` in Svelte.
-
-:::code-group
-
-```tsx [React]
-import { useReference, useStepContent, useStoreGlobal } from '@picked/react/hooks'
-
-export function ProductCategory() {
-  const content = useStepContent()
-  const category = useStoreGlobal(useReference(content?.category))
-
-  if (!category) return null
-
-  return <span>{String(category.data.name ?? '')}</span>
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStepContent, getReference } from '@picked/svelte/hooks'
-
-  const content = getStepContent()
-  const category = getReference(content.map((c) => c?.category ?? null, { skipVoid: false }))
-</script>
-
-{#if $category}
-  <span>{$category.data.name ?? ''}</span>
-{/if}
-```
-
-:::
-
-In Svelte, pass a store and not a plain value. Content arrives after the component
-starts. A plain value therefore holds the result at "not set".
-
-## 2. Resolve a repeatable reference
-
-Use `useReferences()` or `getReferences()`. They give a list in field order.
-
-:::code-group
-
-```tsx [React]
-import { useReferences, useStepContent, useStoreGlobal } from '@picked/react/hooks'
-
-export function ProductCategories() {
-  const content = useStepContent()
-  const categories = useStoreGlobal(useReferences(content?.categories))
-
-  return (
-    <ul>
-      {categories.map((category) => (
-        <li key={category.id}>{String(category.data.name ?? '')}</li>
-      ))}
-    </ul>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStepContent, getReferences } from '@picked/svelte/hooks'
-
-  const content = getStepContent()
-  const categories = getReferences(content.map((c) => c?.categories ?? null, { skipVoid: false }))
-</script>
-
-<ul>
-  {#each $categories as category (category.id)}
-    <li>{category.data.name ?? ''}</li>
-  {/each}
-</ul>
-```
-
-:::
-
-The list holds no empty places, so you need no check for each item.
-
-## Handle a target that does not resolve
-
-A single reference gives an empty result when Picked cannot resolve the target. A
-repeatable reference leaves the item out of the list.
-
-This happens when somebody deleted the target, when the target belongs to another
-workspace, or when the chain of references is deeper than the limit.
-
-Render something else for the empty case, as the React example above does.
-
-## Related
-
-- [Content](/reference/sdk/content) — every hook and its return type.
-- [About content references](/explanation/content-references) — why the entry travels separately.
-- [How to point one entry at another](/how-to/point-one-entry-at-another) — the dashboard side.

package/dist/docs/how-to/register-a-component.md

@@ -1,55 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to register a component
-
-This guide shows you how to connect a component in your application to an experience in
-the dashboard.
-
-## Steps
-
-1. Wrap your component with the adapter for your framework.
-2. Pass it in the `components` object of `createClient()`.
-3. Use the same key as the component name of the experience.
-
-:::code-group
-
-```tsx [React]
-import { createClient } from 'picked'
-import { adaptReactComponent } from '@picked/react'
-import { MyWidget } from './MyWidget'
-
-const picked = createClient({
-  projectId: 'your-project-id',
-  components: {
-    MyWidget: adaptReactComponent(MyWidget),
-  },
-})
-```
-
-```ts [Svelte]
-import { createClient } from 'picked'
-import { adaptSvelteComponent } from '@picked/svelte'
-import MyWidget from './MyWidget.svelte'
-
-const picked = createClient({
-  projectId: 'your-project-id',
-  components: {
-    MyWidget: adaptSvelteComponent(MyWidget),
-  },
-})
-```
-
-:::
-
-:::warning
-`components` takes an adapted component. A plain React or Svelte component does not work
-without `adaptReactComponent` or `adaptSvelteComponent`.
-:::
-
-## Related
-
-- [SDK experiences](/reference/sdk/experiences) — the experience shape.
-- [How to install the SDK](/how-to/install-the-sdk).

package/dist/docs/how-to/register-an-action-handler.md

@@ -1,85 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to register an action handler
-
-This guide shows you how to connect an action node in a flow to a function in your
-application. You need an action in your project first, with a key. See
-[Actions](/reference/dashboard/actions).
-
-A published action that starts a workflow runs without a handler. A handler under its key
-replaces the workflow.
-
-## 1. Register the handler
-
-Pass an `actions` object to `createClient()`. Each key must match an action key from the
-dashboard:
-
-```ts
-import { createClient } from 'picked'
-
-const picked = createClient({
-  projectId: 'your-project-id',
-  actions: {
-    'track-signup': () => {
-      analytics.track('signup_completed')
-    },
-    notify: (params) => {
-      sendNotification(params)
-    },
-  },
-})
-```
-
-The SDK calls the function that matches when the flow reaches the action node.
-
-## 2. Throw only for a true error
-
-The flow takes the failure branch when your handler throws or its promise rejects. Throw
-when the request itself did not complete:
-
-```ts
-'check-eligibility': async () => {
-  const response = await fetch('/api/eligibility')
-  // Throw only when the request itself fails. That takes the failure branch.
-  if (!response.ok) throw new Error('Eligibility request failed')
-}
-```
-
-## 3. Return a response
-
-The value that your handler returns is the response of the action. Code that runs the
-action reads this value:
-
-```ts
-'quote-premium': async ({ responses }) => {
-  const age = responses.find((r) => r.fieldKey === 'age')?.value
-  const { premium } = await fetch(`/api/premium?age=${age}`).then((r) => r.json())
-  return { premium }
-}
-```
-
-## 4. Record a negative answer as a response
-
-A valid negative result is not a failure. An endpoint can answer `200` with a "no". Store
-that value as a response and branch on it with a condition instead:
-
-```ts
-'check-serviced-area': async ({ client, responses }) => {
-  const postcode = responses.find((r) => r.fieldKey === 'postcode')?.value
-  const { serviced } = await fetch(`/api/serviced?postcode=${postcode}`).then((r) => r.json())
-  // Store the outcome as a response. A later condition then takes the branch.
-  client.responses.register('is-serviced', serviced)
-}
-```
-
-## Related
-
-- [About how Picked works](/explanation/how-picked-works#how-an-action-decides-which-way-to-go)
-  — why a returned `false` is a success.
-- [SDK actions](/reference/sdk/actions) — what the handler receives and returns.
-- [How to wait for the response of an action](/how-to/wait-for-an-action-response) — show the
-  response in a component.
-- [Actions](/reference/dashboard/actions) — the dashboard options.