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

package/dist/docs/sdk/predicates.md

@@ -1,128 +0,0 @@
----
-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.
-
-## Define a predicate
-
-Define your predicates when you create the Picked client. Pass a `predicates` object.
-Each predicate needs a unique identifier and a function that takes a state snapshot:
-
-```ts
-import { createClient } from '@picked/client'
-
-const client = createClient({
-  projectId: 'your-project-id',
-  predicates: {
-    'is-example-page': ({ location }) => {
-      return location?.pathname === '/example'
-    },
-    'get-account-tier': async () => {
-      const data = await fetch('/api/get-account-tier').then((r) => r.json())
-      return data.result // Returns "trial".
-    },
-  },
-})
-```
-
-## How predicates work
-
-After you register a predicate and a condition uses it, the SDK follows this flow:
-
-1. **Registration**: you register each predicate on the Picked client at startup.
-2. **State snapshot**: the SDK gives the predicate a frozen state snapshot. The
-   snapshot holds the current responses, the fields, and the browser context.
-3. **Condition evaluation**: an experience condition invokes the predicate with a
-   fresh snapshot on each call.
-4. **Return types**: a predicate can return a boolean, a string, an array of
-   strings, or `undefined`. It can also return a promise that resolves to one of
-   those.
-
-## Use a predicate in a condition
-
-Most predicates are used inside condition logic, through the `invoke` operator:
-
-```ts
-const myExperience = createExperience({
-  // ... other config
-  condition: {
-    and: [
-      {
-        '==': [
-          {
-            invoke: {
-              var: 'predicates.is-example-page', // Points at a predicate that calls your endpoint.
-            },
-          },
-          true, // Check that the return value is true.
-        ],
-      },
-      {
-        '==': [
-          {
-            invoke: {
-              var: 'predicates.account-tier',
-            },
-          },
-          '/trial', // The condition is true when the string matches.
-        ],
-      },
-    ],
-  },
-})
-```
-
-:::tip
-You can also use a predicate in `validation` logic.
-:::
-
-## 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`.
-:::
-
-## Best practices
-
-- **Keep each predicate pure**: a predicate must be deterministic and free of side
-  effects. The same snapshot must always give the same result.
-- **Handle missing data**: check that a response or a field is there before you read
-  its value. Return `undefined` when the data is not available. Do not throw.
-- **Do not do heavy work**: the SDK can invoke a predicate many times. Keep the logic
-  small and fast.
-- **Use an async predicate only when you must**: the SDK supports one, but it can
-  make the experience slow to appear. Use synchronous logic where you can.
-- **Return one type**: do not return a boolean from a predicate one time and a string
-  the next.
-- **Use a meaningful name**: a predicate ID must say what the predicate evaluates,
-  such as `is-premium-user` or `has-items-in-cart`.
-- **Keep the result of expensive work**: when a predicate must do expensive work, put
-  the result in `localStorage` or `sessionStorage` inside the predicate.
-- **Do not change the snapshot**: the state snapshot is frozen. A change to it throws
-  an error in strict mode.

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

@@ -1,79 +0,0 @@
----
-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.
-
-## Why server-side rendering
-
-The search rank of a Page matters, so the HTML that your server returns must hold the
-content of that Page. A crawler and a social preview both read that HTML directly.
-Neither waits for the JavaScript in the browser. A Page that the server renders
-therefore has its content in the first response, and the client takes over after
-that.
-
-## The flow
-
-```
-projectConfig (Delivery API)
-  -> serialize(client, params) on the server -> PickedSnapshot
-  -> embed snapshot in HTML
-  -> client seeds from snapshot -> renders the same markup -> hydrates
-```
-
-1. Fetch your published `projectConfig` from the [Delivery API](/delivery-api).
-2. Call `serialize()` on the server. It finds which experiences match the URL, reads
-   their content, and returns a `PickedSnapshot` as plain JSON. See
-   [Server Snapshot](/sdk/ssr/serialize).
-3. Embed the snapshot in your HTML payload.
-4. On the client, seed a Picked client from the snapshot. The first paint then
-   matches the markup from the server. Hydrate after that. See
-   [Rendering and Hydration](/sdk/ssr/rendering-and-hydration).
-
-The snapshot carries the exact options that the server chose with, and the condition
-results that it kept. The first render on the client therefore reuses the decisions
-of the server. It does not evaluate them again.
-
-## React and Svelte side by side
-
-:::code-group
-
-```tsx [React]
-import { PickedProvider, ExperienceSlot } from '@picked/react'
-
-<PickedProvider options={options} snapshot={snapshot}>
-  <ExperienceSlot name="page" />
-</PickedProvider>
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { ExperienceSlot, setPickedContext } from '@picked/svelte'
-
-  setPickedContext({ options, snapshot })
-</script>
-
-<ExperienceSlot name="page" />
-```
-
-:::
-
-## 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](/sdk/ssr/serialize) for the `serialize()` reference. Go to
-[Rendering and Hydration](/sdk/ssr/rendering-and-hydration) to connect React and
-Svelte. Go to [Slots and Placements](/sdk/ssr/slots-and-placements) for how a slot
-chooses an experience. If the SDK is new to you, read
-[Installation](/sdk) first.

package/dist/docs/sdk/steps.md

@@ -1,479 +0,0 @@
----
-layout: docs
----
-
-# Steps
-
-Render your steps with `<StepRouter>` and `<Step>` from `@picked/react` or
-`@picked/svelte`. Reach the active step through `useStep()` or `getStep()`.
-
-## How steps work
-
-When an experience starts, its steps form a directed graph of nodes. The SDK walks
-this graph to find which step to show:
-
-1. **Initialization**: when the experience opens, the SDK starts at the origin node.
-   It walks the graph to find the first step.
-2. **Step entry**: the SDK sets the active step. It sends a `step_enter` event on the
-   event bus.
-3. **Field evaluation**: the SDK evaluates the fields of the step. It shows or hides
-   a field with a condition, and the current state decides which.
-4. **User input**: the user fills in the fields of the step. Validation runs in the
-   browser on blur and on submit.
-5. **Step submission**: when the user submits, a `step_submit` event fires. The SDK
-   commits the field responses to the client state.
-6. **Navigation**: the SDK follows the edge from the current step node to the next
-   one. It walks through each condition and action on the way.
-7. **Completion**: when no step remains, the experience flow is complete.
-
-## Step routing
-
-`StepRouter` watches the current step state of the experience. It activates the
-`Step` whose `id` matches. Each `Step` registers itself on mount and unregisters on
-unmount, so a tab or a drawer that renders lazily works with no extra code.
-
-:::code-group
-
-```svelte [Svelte]
-<script lang="ts">
-  import { StepRouter, Step } from '@picked/svelte/router'
-</script>
-
-<StepRouter>
-  <Step id="welcome">
-    <WelcomeScreen />
-  </Step>
-
-  <Step id="contact">
-    <ContactForm />
-  </Step>
-
-  <Step id="confirmation">
-    <ConfirmationScreen />
-  </Step>
-</StepRouter>
-```
-
-```tsx [React]
-import { StepRouter, Step } from '@picked/react/router'
-
-function MyExperience() {
-  return (
-    <StepRouter>
-      <Step id="welcome">
-        <WelcomeScreen />
-      </Step>
-
-      <Step id="contact">
-        <ContactForm />
-      </Step>
-
-      <Step id="confirmation">
-        <ConfirmationScreen />
-      </Step>
-    </StepRouter>
-  )
-}
-```
-
-:::
-
-:::note
-A router must hold every Step, even when there is only one Step.
-:::
-
-### Lazy-loaded steps
-
-For a large experience, load a step lazily with a dynamic import:
-
-:::code-group
-
-```svelte [Svelte]
-<StepRouter>
-  <Step id="welcome" component={import('./WelcomeScreen.svelte')} />
-</StepRouter>
-```
-
-```tsx [React]
-import { lazy } from 'react'
-
-const WelcomeScreen = lazy(() => import('./WelcomeScreen'))
-
-<StepRouter>
-  <Step id="welcome">
-    <WelcomeScreen />
-  </Step>
-</StepRouter>
-```
-
-:::
-
-The `component` prop takes a `Promise<Component>`. The SDK does not load the content
-of the step until that step becomes active.
-
-## Reach the step context
-
-Inside a `Step` component, or inside any component that a `Step` renders, call
-`getStep()` or `useStep()` to reach the reactive context of the step:
-
-:::code-group
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStep } from '@picked/svelte/hooks'
-
-  const { step, fields } = getStep()
-</script>
-
-<h1>{$step.label}</h1>
-
-{#each $fields as field}
-  <label>{field.label}</label>
-  <input
-    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}
-{/each}
-```
-
-```tsx [React]
-import { useStep } from '@picked/react/hooks'
-import { useUnit } from 'effector-react'
-
-function ContactForm() {
-  const { step, fields } = useStep()
-  const currentStep = useUnit(step)
-  const currentFields = useUnit(fields)
-
-  return (
-    <>
-      <h1>{currentStep.label}</h1>
-
-      {currentFields.map((field) => (
-        <div key={field.id}>
-          <label>{field.label}</label>
-          <input
-            name={field.id}
-            value={field.value ?? ''}
-            onChange={field.onChange}
-            onBlur={field.onBlur}
-          />
-          {field.error && field.touched && <p className="error">{field.error.userMessage}</p>}
-        </div>
-      ))}
-    </>
-  )
-}
-```
-
-:::
-
-`getStep()` in Svelte, and `useStep()` in React, return a `StepContext` with these
-properties:
-
-| Property   | Type                                          | Description                                                                    |
-| ---------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
-| `step`     | `Store<ExperienceStep>`                       | A reactive store that holds the `id` and the `label` of the step                |
-| `fields`   | `Store<FormField[]>`                          | A reactive store of the fields, with their current values, errors, and handlers |
-| `isActive` | `Store<boolean>` (Svelte) / `boolean` (React) | Whether the router holds this step as the active one                            |
-| `form`     | Object                                        | The handlers for a form submission. See [Forms](#forms).                        |
-
-## Forms
-
-When a step has fields, `getStep()` and `useStep()` give you a `form` object. Use it
-for the submission, the validation, and the move to the next step.
-
-Both take an optional object of callbacks, as in `getStep({ onSuccess })` or
-`useStep({ onSuccess })`. This is the recommended way to act on a submission. The
-slots are `onBeforeSubmit`, `onSuccess`, and `onError`. This page covers each one
-below.
-
-### Handle a submission
-
-Bind `form.props` to the `onsubmit` handler of your `<form>` element:
-
-:::code-group
-
-```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}
-    <input
-      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}
-  {/each}
-
-  <button type="submit" disabled={$isSubmitting}>
-    {$isSubmitting ? 'Submitting…' : 'Continue'}
-  </button>
-</form>
-```
-
-```tsx [React]
-import { useStep } from '@picked/react/hooks'
-import { useUnit } from 'effector-react'
-
-function StepForm() {
-  const { fields, form } = useStep()
-  const currentFields = useUnit(fields)
-  const isSubmitting = useUnit(form.submitting)
-
-  return (
-    <form {...form.props}>
-      {currentFields.map((field) => (
-        <div key={field.id}>
-          <input
-            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}>
-        {isSubmitting ? 'Submitting…' : 'Continue'}
-      </button>
-    </form>
-  )
-}
-```
-
-:::
-
-When you submit the form, the SDK does this:
-
-1. It collects the field values from the HTML form.
-2. It runs each `onBeforeSubmit` callback, one after another. A throw here aborts the
-   submit and commits nothing.
-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. A call to `stopNavigation` stops this. A callback that
-   failed in step 6 does not stop it.
-
-### Transform data before a submission
-
-Use `onBeforeSubmit` to intercept and transform the field data before the SDK stores it. The callbacks run one after another. Each one takes the output of the one before
-it:
-
-:::code-group
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStep } from '@picked/svelte/hooks'
-
-  const { form } = getStep({
-    onBeforeSubmit: async (data) => {
-      // Normalize the email address to lowercase first.
-      return {
-        ...data,
-        'email-address': String(data['email-address']).toLowerCase(),
-      }
-    },
-  })
-</script>
-
-<form {...form.props}>{/* ... */}</form>
-```
-
-```tsx [React]
-import { useStep } from '@picked/react/hooks'
-
-function ContactStep() {
-  const { form } = useStep({
-    onBeforeSubmit: async (data) => {
-      // Normalize the email address to lowercase first.
-      return {
-        ...data,
-        'email-address': String(data['email-address']).toLowerCase(),
-      }
-    },
-  })
-
-  return <form {...form.props}>{/* ... */}</form>
-}
-```
-
-:::
-
-:::warning
-When an `onBeforeSubmit` callback throws, the SDK aborts the submit before it commits
-anything, and the step does not advance. This is deliberate. A payload that is only
-part transformed would store data that looks correct but is wrong. Use
-`onBeforeSubmit` for a transform and for a validation check. Put a side effect, such as an
-analytics call or a backend call, in `onSuccess`.
-:::
-
-### Success and error callbacks
-
-Pass `onSuccess` and `onError` to act on the outcome of a submission:
-
-:::code-group
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStep } from '@picked/svelte/hooks'
-
-  const { form } = getStep({
-    onSuccess: ({ data }) => {
-      analytics.track('lead_captured', data)
-    },
-    onError: (errors) => {
-      console.error('Validation errors:', errors)
-    },
-  })
-</script>
-
-<form {...form.props}>{/* ... */}</form>
-```
-
-```tsx [React]
-import { useStep } from '@picked/react/hooks'
-
-function ContactStep() {
-  const { form } = useStep({
-    onSuccess: ({ data }) => {
-      analytics.track('lead_captured', data)
-    },
-    onError: (errors) => {
-      console.error('Validation errors:', errors)
-    },
-  })
-
-  return <form {...form.props}>{/* ... */}</form>
-}
-```
-
-:::
-
-A callback belongs to the component that passes it. The SDK releases the callback
-when that component unmounts, so you write no teardown code. A new inline function on
-a re-render replaces the earlier one and does not add a second one. One submit
-therefore runs each callback exactly one time.
-
-An `onSuccess` or `onError` callback that throws or rejects cannot stop the flow. The
-step still advances, and the SDK reports the failure on the client event bus as
-`form_submit_callback_error`, so the failure stays observable.
-
-#### Register a callback in code
-
-`form.onSuccess`, `form.onError`, and `form.onBeforeSubmit` are an escape hatch, for
-a callback that you must attach only when a condition holds. They return nothing. The
-SDK releases them for you, as above.
-
-```tsx [React]
-function ContactStep({ trackConversions }: { trackConversions: boolean }) {
-  const { form } = useStep()
-
-  if (trackConversions) {
-    form.onSuccess(({ data }) => analytics.track('lead_captured', data))
-  }
-
-  return <form {...form.props}>{/* ... */}</form>
-}
-```
-
-:::warning
-Register from the body of the component, and not from an event handler. A
-registration inside a click handler is added each time the handler runs, and the SDK
-releases it only when the component unmounts. The registrations therefore accumulate.
-Use the options object above where you can.
-:::
-
-### Stop the move to the next step
-
-By default the experience advances to the next step after a successful submission.
-Call `stopNavigation()` inside `onSuccess` to stop this. Do it when you must choose
-the next step yourself:
-
-:::code-group
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStep } from '@picked/svelte/hooks'
-  import { getExperience } from '@picked/svelte/hooks'
-
-  const experience = getExperience()
-
-  const { form } = getStep({
-    onSuccess: ({ data, stopNavigation }) => {
-      stopNavigation()
-
-      // Choose the next step from the data that the user sent.
-      if (data['plan-type'] === 'enterprise') {
-        experience.goToStepById('enterprise-contact')
-      } else {
-        experience.goToNextStep()
-      }
-    },
-  })
-</script>
-
-<form {...form.props}>{/* ... */}</form>
-```
-
-```tsx [React]
-import { useStep } from '@picked/react/hooks'
-import { useExperience } from '@picked/react/hooks'
-
-function PlanStep() {
-  const experience = useExperience()
-
-  const { form } = useStep({
-    onSuccess: ({ data, stopNavigation }) => {
-      stopNavigation()
-
-      // Choose the next step from the data that the user sent.
-      if (data['plan-type'] === 'enterprise') {
-        experience.goToStepById('enterprise-contact')
-      } else {
-        experience.goToNextStep()
-      }
-    },
-  })
-
-  return <form {...form.props}>{/* ... */}</form>
-}
-```
-
-:::
-
-Move by step `id` with `goToStepById('<step-id>')`, or by the `key` of the step with
-`goToStepByKey('<step-key>')`. Both jump directly to the step node that matches. When
-no step matches, the call does nothing.
-
-## Best practices
-
-- **Give each step a meaningful label**: analytics events and the dashboard both show
-  the `label`. Use a name that says what the step does, such as `"Contact Details"`
-  and not `"Step 2"`.
-- **Keep each step small**: each step must collect one small set of related
-  information. More steps with fewer fields each reduce the number of users who leave.
-- **Use a condition to take a branch**: do not make a second copy of a step. Write the
-  branch with `nextConditional()`, so that you can reuse a shared step.
-- **Use `stopNavigation` only when you must**: an automatic move after a submit is
-  what a user expects. Stop it only when you must choose the next step yourself.
-- **Check a field on blur, not on change**: the SDK does this for you. A field shows
-  an error after the user leaves it, and not while the user types.
-- **Load a large step component lazily**: use the `component` prop on `<Step>` with a
-  dynamic import, for content that only some users see.