@picked/client 0.0.1-dev.1789541668638 → 0.0.1-next.1

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,67 +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).
-
-## 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. 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.
-- [Actions](/reference/dashboard/actions) — the dashboard options.

package/dist/docs/how-to/render-a-step-form.md

@@ -1,131 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to render a step form
-
-This guide shows you how to render the fields of the active step and let a visitor submit
-them.
-
-## 1. Put the steps in a router
-
-`StepRouter` watches the step state and activates the `Step` whose `id` matches.
-
-:::code-group
-
-```tsx [React]
-import { StepRouter, Step } from '@picked/react/router'
-
-function MyExperience() {
-  return (
-    <StepRouter>
-      <Step id="welcome">
-        <WelcomeScreen />
-      </Step>
-      <Step id="contact">
-        <ContactForm />
-      </Step>
-    </StepRouter>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { StepRouter, Step } from '@picked/svelte/router'
-</script>
-
-<StepRouter>
-  <Step id="welcome">
-    <WelcomeScreen />
-  </Step>
-  <Step id="contact">
-    <ContactForm />
-  </Step>
-</StepRouter>
-```
-
-:::
-
-:::note
-A router must hold every Step, even when there is only one Step.
-:::
-
-## 2. Render the fields
-
-Bind `form.props` to your `<form>` element and map over the fields.
-
-:::code-group
-
-```tsx [React]
-import { useStep, useStoreGlobal } from '@picked/react/hooks'
-
-function StepForm() {
-  const { fields, form } = useStep()
-  const currentFields = useStoreGlobal(fields)
-  const isSubmitting = useStoreGlobal(form.submitting)
-
-  return (
-    <form {...form.props}>
-      {currentFields.map((field) => (
-        <div key={field.id}>
-          <label htmlFor={field.id}>{field.label}</label>
-          <input
-            id={field.id}
-            name={field.id}
-            value={field.value ?? ''}
-            onChange={field.onChange}
-            onBlur={field.onBlur}
-          />
-          {field.error && field.touched && <p className="error">{field.error.userMessage}</p>}
-        </div>
-      ))}
-      <button type="submit" disabled={isSubmitting}>Continue</button>
-    </form>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStep } from '@picked/svelte/hooks'
-
-  const { fields, form } = getStep()
-  const isSubmitting = form.submitting
-</script>
-
-<form {...form.props}>
-  {#each $fields as field}
-    <div>
-      <label for={field.id}>{field.label}</label>
-      <input
-        id={field.id}
-        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}
-    </div>
-  {/each}
-  <button type="submit" disabled={$isSubmitting}>Continue</button>
-</form>
-```
-
-:::
-
-The SDK checks a field on blur, and not while the visitor types.
-
-## 3. Load a large step lazily
-
-Pass a dynamic import to the `component` prop of `<Step>`. The SDK does not load the
-content until that step becomes active.
-
-## Related
-
-- [How to run code on a form submission](/how-to/run-code-on-a-form-submission) — the
-  callbacks.
-- [SDK steps](/reference/sdk/steps) — the `StepContext` shape.

package/dist/docs/how-to/render-an-unpublished-preview.md

@@ -1,41 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to render an unpublished preview
-
-This guide shows you how to render draft content on your server. Your server cannot read
-the query string of the browser, so you must pass the token yourself.
-
-## 1. Get the token
-
-The management API holds the preview token of a workspace in the `previewToken` field. The
-preview action in the dashboard also makes one for you.
-
-## 2. Read the config with the token
-
-```bash
-curl "https://api.picked.app/api/v1/projects/proj_123?preview_token=<token>"
-```
-
-A preview response returns `versionId: null`. An invalid token returns `401`.
-
-## 3. Pass the same token to `serialize()`
-
-```ts
-const snapshot = await serialize(client, {
-  projectConfig,
-  attributes: { location: { pathname: '/promo' } },
-  previewToken,
-})
-```
-
-Use the same token for both requests. The configuration and the content then come from the same
-preview.
-
-## Related
-
-- [About the two APIs](/explanation/the-two-apis) — how a preview stays out of the search
-  index.
-- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).

package/dist/docs/how-to/reuse-a-section.md

@@ -1,53 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to reuse a section
-
-This guide shows you how to define a common structure one time and use it in more than
-one Model.
-
-## 1. Create the section
-
-1. Click **Pages** in the sidebar.
-2. Click **Page Sections**.
-3. Click **New block**.
-4. Enter a **Name** and a **Key**.
-5. Add your fields.
-6. Click **Create block**.
-
-The **Category** is **Section** already, because you opened the list from **Page
-Sections**.
-
-## 2. Accept the section in a Model
-
-1. Open a page layout or a step layout.
-2. Add a **Page Sections** field to the schema.
-3. Click **Save**.
-
-The field now accepts any Block of the Section category. Make the field repeatable to
-build a page from a list of sections.
-
-If you want one section at a fixed place instead of a list, add a **Content block** field.
-Set its **Block category** to the **Section** category.
-
-## 3. Choose the section in an entry
-
-1. Open a content entry that uses the Model.
-2. Find the field that you added.
-3. Choose your Block.
-4. Fill in the fields of the Block.
-5. Click **Save**.
-
-:::warning
-An edit to a Block does not migrate the entries that use it. Check each affected content
-entry again, and correct every field error before you publish.
-:::
-
-## Related
-
-- [About the content model](/explanation/the-content-model) — why a schema change does not
-  migrate your data.
-- [Blocks](/reference/dashboard/content/blocks) — the reference.
-- [Models](/reference/dashboard/content/models) — every field type.

package/dist/docs/how-to/reuse-a-step-field-or-action.md

@@ -1,28 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to reuse a step, a field, or an action
-
-This guide shows you how to use one step, field, action, or condition in more than one
-flow. All four belong to the project, and not to the experience that you made them in.
-
-## Steps
-
-1. Open the flow builder for the second experience.
-2. Find the step, the action, or the condition in the library on the left.
-3. Drag it onto the canvas, or onto a step node for a field.
-
-The same one now appears in both flows.
-
-:::warning
-A change to the options applies at every place that uses it. Check the other flows before
-you change a shared step, field, action, or condition.
-:::
-
-## Related
-
-- [Steps](/reference/dashboard/steps) — the step options.
-- [Fields](/reference/dashboard/fields) — the field options.
-- [Actions](/reference/dashboard/actions) — the action options.

package/dist/docs/how-to/roll-back-a-published-version.md

@@ -1,26 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to roll back a published version
-
-This guide shows you how to make an earlier published version live again. Your current
-draft does not change.
-
-## Steps
-
-1. Open **Publish history** from the project sidebar.
-2. Find the version that you want to restore.
-3. Click **Restore**.
-4. Read the diff preview. It compares the current live version against the one that you
-   chose.
-5. Click **Restore this version** to confirm.
-
-The restored version is live immediately.
-
-## Related
-
-- [About workspaces and versions](/explanation/workspaces-and-versions) — why a roll-back
-  changes no data.
-- [Publish history](/reference/dashboard/workspace-versioning) — the version list.

package/dist/docs/how-to/run-an-ab-test.md

@@ -1,49 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to run an A/B test
-
-This guide shows you how to split your traffic with a feature flag and read the result in
-your application.
-
-Read [About feature flag allocation](/explanation/feature-flag-allocation) first. The
-point at which you read the feature flag decides when a visitor enters the test.
-
-## 1. Create the feature flag
-
-1. Open your project.
-2. Click **Feature flags** in the sidebar.
-3. Click **New feature flag**.
-4. Enter a name.
-5. Click **Create feature flag**.
-
-You cannot change the key after you create the feature flag.
-
-## 2. Set the allocation
-
-Open the detail page of the feature flag and set these controls:
-
-1. Turn **Enabled** on. A feature flag that is off allocates nobody.
-2. Set **Weight** to the percentage of visitors that you want in the test.
-3. Enter a **Description** that says what the feature flag tests.
-
-## 3. Read the feature flag in your application
-
-See [How to read a feature flag](/how-to/read-a-feature-flag). Read it at the point where
-the decision matters, and not at startup.
-
-## 4. Change the weight later
-
-1. Change **Weight** on the detail page.
-2. Increment the version.
-
-The new weight then applies to a visitor with a cached decision. Leave the version as it
-is to apply the new weight only to a visitor who is not allocated yet.
-
-## Related
-
-- [About feature flag allocation](/explanation/feature-flag-allocation) — why two feature
-  flags at the same weight give four groups, not two.
-- [Feature flags](/reference/dashboard/features) — the controls.

package/dist/docs/how-to/run-code-on-a-form-submission.md

@@ -1,125 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to run code on a form submission
-
-This guide shows you how to act on a step submission. Pass your callbacks to `useStep()`
-in React, or to `getStep()` in Svelte.
-
-## What the SDK does on submit
-
-1. It collects the field values from the HTML form.
-2. It runs each `onBeforeSubmit` callback, one after another.
-3. It checks each required field and each validation rule.
-4. It commits the responses to the experience state.
-5. It fires `form_submit_success` or `form_submit_error` on the event bus.
-6. It runs your `onSuccess` or `onError` callback.
-7. It moves to the next step.
-
-## Change the data before it is stored
-
-:::code-group
-
-```tsx [React]
-const { form } = useStep({
-  onBeforeSubmit: async (data) => ({
-    ...data,
-    'email-address': String(data['email-address']).toLowerCase(),
-  }),
-})
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  const { form } = getStep({
-    onBeforeSubmit: async (data) => ({
-      ...data,
-      'email-address': String(data['email-address']).toLowerCase(),
-    }),
-  })
-</script>
-```
-
-:::
-
-:::warning
-An `onBeforeSubmit` callback that throws aborts the submit before the SDK commits
-anything, and the step does not advance. Use it for a transform and for a check. Put a
-side effect, such as an analytics call, in `onSuccess`.
-:::
-
-## Act on the outcome
-
-:::code-group
-
-```tsx [React]
-const { form } = useStep({
-  onSuccess: ({ data }) => analytics.track('lead_captured', data),
-  onError: (errors) => console.error('Validation errors:', errors),
-})
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  const { form } = getStep({
-    onSuccess: ({ data }) => analytics.track('lead_captured', data),
-    onError: (errors) => console.error('Validation errors:', errors),
-  })
-</script>
-```
-
-:::
-
-A callback belongs to the component that passes it, and the SDK releases it when that
-component unmounts. An `onSuccess` callback that throws cannot stop the flow. The SDK
-reports the failure as `form_submit_callback_error`.
-
-## Choose the next step yourself
-
-Call `stopNavigation()` inside `onSuccess`, then move where you want:
-
-:::code-group
-
-```tsx [React]
-const experience = useExperience()
-
-const { form } = useStep({
-  onSuccess: ({ data, stopNavigation }) => {
-    stopNavigation()
-    if (data['plan-type'] === 'enterprise') {
-      experience.goToStepById('enterprise-contact')
-    } else {
-      experience.goToNextStep()
-    }
-  },
-})
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  const experience = getExperience()
-
-  const { form } = getStep({
-    onSuccess: ({ data, stopNavigation }) => {
-      stopNavigation()
-      if (data['plan-type'] === 'enterprise') {
-        experience.goToStepById('enterprise-contact')
-      } else {
-        experience.goToNextStep()
-      }
-    },
-  })
-</script>
-```
-
-:::
-
-`goToStepById()` takes a step `id`. `goToStepByKey()` takes the key of the step. When no
-step matches, the call does nothing.
-
-## Related
-
-- [How to render a step form](/how-to/render-a-step-form).
-- [SDK steps](/reference/sdk/steps) — the `form` object.