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

package/dist/docs/sdk/steps.md

@@ -1,434 +0,0 @@
----
-layout: docs
----
-
-# Steps
-
-Render steps with `<StepRouter>` and `<Step>` from `@picked/react` or `@picked/svelte`, and access the active step through `useStep()` / `getStep()`.
-
-## How steps work
-
-When an experience starts, its steps are connected in a directed node graph. The SDK traverses this graph to determine which step to display:
-
-1. **Initialization**: When the experience opens, the SDK starts at the origin node and traverses the graph to find the first step
-2. **Step Entry**: The active step is set and a `step_enter` event is emitted on the event bus
-3. **Field Evaluation**: The step's fields are evaluated — fields with conditions are shown or hidden based on the current state
-4. **User Input**: The user interacts with the step's fields. Client-side validation runs on blur and on submit
-5. **Step Submission**: When the user submits, a `step_submit` event fires and field responses are committed to the client state
-6. **Navigation**: The SDK follows the edge from the current step node to the next, traversing any conditionals or actions before arriving at the next step
-7. **Completion**: When no further steps exist, the experience flow is complete
-
-## Step routing
-
-`StepRouter` listens to the experience's current step state and activates the matching `Step` by its `id`. Each `Step` registers itself on mount and unregisters on unmount, so lazy-rendered tabs or drawers work automatically.
-
-:::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
-All Steps must be wrapped in a router, even if it is a single Step
-:::
-
-### Lazy-loaded steps
-
-For large experiences, steps can be lazily loaded using dynamic imports:
-
-:::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 accepts a `Promise<Component>` — the step's content is not loaded until it becomes active.
-
-## Accessing step context
-
-Inside a `Step` component (or any component rendered within one), call `getStep()` / `useStep()` to access the step's reactive context:
-
-:::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()` (Svelte) / `useStep()` (React) returns a `StepContext` with the following properties:
-
-| Property   | Type                                          | Description                                                                    |
-| ---------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
-| `step`     | `Store<ExperienceStep>`                       | Reactive store containing the step's `id` and `label`                          |
-| `fields`   | `Store<FormField[]>`                          | Reactive store of fields with their current values, errors, and event handlers |
-| `isActive` | `Store<boolean>` (Svelte) / `boolean` (React) | Whether this step is currently active in the router                            |
-| `form`     | Object                                        | Form submission handlers (see [Forms](#forms))                                 |
-
-## Forms
-
-When a step has fields, `getStep()` / `useStep()` provides a `form` object for handling submission, validation, and navigation.
-
-Both accept an optional callbacks object — `getStep({ onSuccess })` / `useStep({ onSuccess })` — which is the recommended way to react to submission. The available slots are `onBeforeSubmit`, `onSuccess` and `onError`, all covered below.
-
-### Handling submission
-
-Bind `form.props` to your `<form>` element's `onsubmit` handler:
-
-:::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>
-  )
-}
-```
-
-:::
-
-Submitting the form:
-
-1. Collects field values from the HTML form
-2. Runs `onBeforeSubmit` transform callbacks in series — a throw here aborts the submit before anything is committed
-3. Validates all required fields and field validation rules
-4. Commits the responses to the experience state
-5. Fires `form_submit_success` or `form_submit_error` on the event bus
-6. Runs your `onSuccess` or `onError` callbacks
-7. Navigates to the next step (unless `stopNavigation` is called, and regardless of whether a callback in step 6 failed)
-
-### Transforming data before submission
-
-Use `onBeforeSubmit` to intercept and transform field data before it is committed. Callbacks run in series, each receiving the output of the previous:
-
-:::code-group
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStep } from '@picked/svelte/hooks'
-
-  const { form } = getStep({
-    onBeforeSubmit: async (data) => {
-      // Normalize email to lowercase before committing
-      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 email to lowercase before committing
-      return {
-        ...data,
-        'email-address': String(data['email-address']).toLowerCase(),
-      }
-    },
-  })
-
-  return <form {...form.props}>{/* ... */}</form>
-}
-```
-
-:::
-
-:::warning
-If an `onBeforeSubmit` callback throws, the submit is aborted before anything is committed and the step does not advance. This is deliberate — committing a half-transformed payload would persist wrong-but-plausible data. Use it for transforms and validation, and put side effects such as analytics or backend calls in `onSuccess` instead.
-:::
-
-### Success and error callbacks
-
-Pass `onSuccess` and `onError` to react to submission outcomes:
-
-:::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>
-}
-```
-
-:::
-
-Callbacks are scoped to the component that passes them, and are cleaned up automatically when that component unmounts — no manual teardown is needed. Passing a new inline function on a re-render replaces the previous one rather than adding another, so a single submit runs each callback exactly once.
-
-A throwing or rejecting `onSuccess`/`onError` callback cannot block the flow: the step still advances, and the failure is reported on the client event bus as `form_submit_callback_error` so it stays observable.
-
-#### Registering callbacks imperatively
-
-`form.onSuccess`, `form.onError` and `form.onBeforeSubmit` are also available as an escape hatch, for cases where a callback has to be attached conditionally. They return nothing — cleanup is automatic, 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 component body, not from an event handler. A registration made inside a click handler is added each time the handler runs and is only released when the component unmounts, so it accumulates. Prefer the options object above wherever you can.
-:::
-
-### Preventing navigation on success
-
-By default, the experience advances to the next step after a successful submission. Call `stopNavigation()` inside `onSuccess` to prevent this, for example when you need to handle navigation manually:
-
-:::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()
-
-      // Navigate to step based on submitted data
-      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()
-
-      // Decide the next step based on submitted data
-      if (data['plan-type'] === 'enterprise') {
-        experience.goToStepById('enterprise-contact')
-      } else {
-        experience.goToNextStep()
-      }
-    },
-  })
-
-  return <form {...form.props}>{/* ... */}</form>
-}
-```
-
-:::
-
-Navigate by step `id` with `goToStepById('<step-id>')`, or by the step's semantic `key` with `goToStepByKey('<step-key>')`. Both jump straight to the matching step node; if no step matches, the call is a no-op.
-
-## Best practices
-
-- **Give steps meaningful labels**: The `label` is used in analytics events and the dashboard — prefer descriptive names like `"Contact Details"` over `"Step 2"`
-- **Keep steps focused**: Each step should collect a small, related set of information. Prefer more steps over longer forms to reduce abandonment
-- **Use conditionals for branching**: Avoid duplicating steps — model branching logic with `nextConditional()` so shared steps can be reused
-- **Use `stopNavigation` sparingly**: Automatic navigation after submit is the expected behavior. Only disable it when you need explicit control over the next destination
-- **Validate eagerly on blur, not on change**: The SDK follows this pattern automatically — fields show errors after the user leaves them, not as they type
-- **Lazy-load large step components**: Use the `component` prop on `<Step>` with a dynamic import for content that is only shown to a subset of users

package/dist/docs/steps.mdx

@@ -1,44 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# Steps
-
-A step is a visual screen or card shown to visitors during an experience. Each step holds one or more fields that collect data or display content.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/steps"
-  alt="The steps list for a workspace on the Picked dashboard"
-/>
-
-## Create a step
-
-1. Open your project.
-2. Click **Steps** in the sidebar.
-3. Click **New Step**.
-4. Enter a name and key.
-5. Click **Create**.
-
-The key is a unique identifier used in your application. It's set once and can't be changed later.
-
-## Configure a step
-
-**Name**: The display name shown in the dashboard. Not visible to visitors.
-
-**Key**: The programmatic identifier used by your application to reference this step. Not visible to visitors.
-
-**Layout Name**: The name of the component layout used to render this step. For example, `card`, `modal`, or `fullscreen`.
-
-A step can also carry a **Step Layout**, a reusable CMS schema that backs the step with a Content Entry. See [Page & Step Layouts](/content/layouts).
-
-## Assign fields
-
-In the flow builder, drag a field from the entity browser onto a step node. The field appears in the step's **Assigned Fields** list in the inspector.
-
-You can also view and manage assigned fields by selecting the step node and expanding the **Assigned Fields** section. Click any field to open its inspector.
-
-## Reuse steps
-
-Steps are project-level entities. You can drag the same step into multiple experience flows. Changes to a step's configuration apply everywhere it's used.

package/dist/docs/team-management.md

@@ -1,40 +0,0 @@
----
-layout: docs
----
-
-# Team management
-
-Manage who has access to your organization and what they can do. Organizations are the top-level container for projects and members.
-
-## Organizations
-
-An organization groups your projects, members, and settings. You can belong to multiple organizations.
-
-Switch between organizations using the organization selector in the top of the sidebar.
-
-## Invite members
-
-1. Open your organization.
-2. Click **Members**.
-3. Click **Invite**.
-4. Enter an email address.
-5. Select a role.
-6. Click **Send Invite**.
-
-The invited user receives an email with a link to join your organization. They need to create a Picked account if they don't have one.
-
-## Remove members
-
-1. Open your organization.
-2. Click **Members**.
-3. Find the member you want to remove.
-4. Click **Remove** next to their name.
-5. Confirm the removal.
-
-The member immediately loses access to all projects in the organization.
-
-## Roles and permissions
-
-Members are assigned roles that control what they can access. Roles determine whether a member can create projects, edit experiences, manage other members, or view reports.
-
-Assign the minimum role needed for each member's responsibilities.

package/dist/docs/vite-plugin.md

@@ -1,82 +0,0 @@
----
-layout: docs
----
-
-# Vite Plugin
-
-`@picked/vite-plugin-picked` integrates Picked into your Vite project. It fetches your project configuration at build time and injects it via Vite's `define`, eliminating the runtime API request. During development it also serves a launcher page for previewing experiences with feature overrides.
-
-## Installation
-
-:::code-group
-
-```bash [npm]
-npm install @picked/vite-plugin-picked
-```
-
-```bash [pnpm]
-pnpm add @picked/vite-plugin-picked
-```
-
-```bash [yarn]
-yarn add @picked/vite-plugin-picked
-```
-
-:::
-
-## Setup
-
-Add the plugin to your `vite.config.ts`:
-
-```typescript
-import { defineConfig } from 'vite'
-import { picked } from '@picked/vite-plugin-picked'
-
-export default defineConfig({
-  plugins: [
-    picked({
-      projectId: 'your-project-id',
-    }),
-  ],
-})
-```
-
-## How It Works
-
-### Build-Time Config Injection
-
-When Vite starts (both `dev` and `build`), the plugin:
-
-1. Fetches your project configuration from the Picked API
-2. Embeds the config directly into your bundle
-3. The SDK reads the embedded config at runtime, skipping the network request
-
-When a preview token is present at runtime, the SDK ignores the build-time config and fetches fresh data from the API.
-
-### Dev Launcher
-
-During development, the plugin serves an HTML page at `/` that lets you:
-
-- See all features in your project with their current status
-- Toggle features on/off for local testing
-- Preview experiences with specific feature overrides
-
-After the dev server starts, the launcher URL appears alongside Vite's native output:
-
-```
-  ➜  Picked:  http://localhost:5173/
-  ➜  Local:   http://localhost:5173/
-  ➜  Network: use --host to expose
-```
-
-## Options
-
-| Option           | Type      | Default                      | Description                                              |
-| ---------------- | --------- | ---------------------------- | -------------------------------------------------------- |
-| `projectId`      | `string`  | —                            | **Required.** Your Picked project ID.                    |
-| `apiUrl`         | `string`  | `https://api.picked.app`     | Custom API URL for self-hosted or local API instances.    |
-| `disableLauncher`| `boolean` | `false`                      | Disable the launcher page in both dev and build output.  |
-
-## Build Output
-
-When building for production (`vite build`), the plugin emits an `index.html` file containing the launcher page (unless `disableLauncher` is set). This lets you deploy the launcher alongside your application for stakeholder previews.

package/dist/docs/workspace-versioning.mdx

@@ -1,28 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# Workspace versioning
-
-Every publish creates an immutable snapshot of your workspace. The project always serves exactly one version — the *live* version. Rolling back moves the project's live pointer to an earlier snapshot without modifying any data.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/publish-history"
-  alt="The Publish history page showing published workspace versions with Live and Restore actions"
-  hide={['[data-testid="version-row-relative-time"]']}
-/>
-
-## Publish history
-
-The **Publish history** page lists every published version across all workspaces in the project, newest first. The currently-served version carries a **Live** badge.
-
-## Rolling back to a previous version
-
-1. Open **Publish history** from the project sidebar.
-2. Find the version you want to restore and click **Restore**.
-3. Review the diff preview — it shows what changes between the current live version and the target.
-4. Click **Restore this version** to confirm.
-
-The restored version is immediately live. Your current draft is left untouched.