@picked/client 0.0.55 → 0.0.56-next.2

package/dist/docs/sdk/steps.md

@@ -0,0 +1,411 @@
+---
+layout: docs
+---
+
+# Steps
+
+Steps are the building blocks of an experience. Each step represents a single screen or stage in a multi-step journey.
+
+## 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 section)                                   |
+
+## Forms
+
+When a step has fields, `getStep()` / `useStep()` provides a `form` object for handling submission, validation, and navigation.
+
+### 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 `onSubmit` transform callbacks (if any)
+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. Navigates to the next step (unless `stopNavigation` is called)
+
+### Transforming Data Before Submission
+
+Use `form.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()
+
+  form.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()
+
+  form.onBeforeSubmit(async (data) => {
+    // Normalize email to lowercase before committing
+    return {
+      ...data,
+      'email-address': String(data['email-address']).toLowerCase(),
+    }
+  })
+
+  return <form {...form.props}>{/* ... */}</form>
+}
+```
+
+:::
+
+### Success and Error Callbacks
+
+Register callbacks for submission outcomes using `form.onSuccess` and `form.onError`:
+
+:::code-group
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStep } from '@picked/svelte/hooks'
+
+  const { form } = getStep()
+
+  form.onSuccess(async ({ data }) => {
+    // Call your backend after responses are committed
+    await fetch('/api/submit', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    })
+  })
+
+  form.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()
+
+  form.onSuccess(async ({ data }) => {
+    // Call your backend after responses are committed
+    await fetch('/api/submit', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    })
+  })
+
+  form.onError((errors) => {
+    console.error('Validation errors:', errors)
+  })
+
+  return <form {...form.props}>{/* ... */}</form>
+}
+```
+
+:::
+
+Callbacks registered via `onSuccess` and `onError` are automatically cleaned up when the component unmounts — no manual teardown is needed.
+
+### 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 { form } = getStep()
+  const experience = getExperience()
+
+  form.onSuccess(async ({ 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 { form } = useStep()
+  const experience = useExperience()
+
+  form.onSuccess(async ({ 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>
+}
+```
+
+:::
+
+## 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.md

@@ -0,0 +1,35 @@
+---
+layout: docs
+---
+
+# 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.
+
+## 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`.
+
+## 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

@@ -0,0 +1,40 @@
+---
+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/tooling/chrome-extension.md

@@ -0,0 +1,29 @@
+---
+layout: docs
+---
+
+# Chrome Extension
+
+The Picked Developer Tools extension adds a Picked panel to Chrome DevTools for inspecting and debugging your Picked integration on any page running the SDK.
+
+![Picked Developer Tools](/chrome-extension-screenshot.jpg)
+
+## Installation
+
+Install from the [Chrome Web Store](https://chromewebstore.google.com/detail/picked-developer-tools/nimmdamgnhlhdpngnalkpmnleebngidh).
+
+## Setup
+
+Add the `svelteDevtoolsPlugin` to your Picked client so the extension can connect to the SDK.
+
+```typescript
+import { createPicked } from '@picked/client'
+import { svelteDevtoolsPlugin } from '@picked/svelte/plugins/devtools'
+
+const picked = createPicked({
+  projectId: 'your-project-id',
+  plugins: [
+    svelteDevtoolsPlugin(),
+  ],
+})
+```

package/dist/docs/tooling/gtm-template.md

@@ -0,0 +1,69 @@
+---
+layout: docs
+---
+
+# Google Tag Manager template
+
+The Picked Ecommerce GTM Tag Template lets you track ecommerce events and send them to Picked directly from Google Tag Manager.
+
+## Automatic installation
+
+Install the template from the GTM Community Gallery:
+
+1. In Tag Manager, click **Templates**.
+2. In the **Tag Templates** section, click **Search Gallery**.
+3. Search for `Picked Ecommerce`.
+4. Click the Picked Ecommerce template to view details.
+5. Click **Add to workspace**.
+6. Review the required permissions and click **Add**.
+
+![Picked Ecommerce template in the GTM Community Gallery](/gtm/picked-ecommerce-gtm.png)
+
+## Manual installation
+
+If you prefer to import the template file directly:
+
+1. Download the [template file](https://github.com/picked-app/gtm-template/blob/main/template.tpl) from GitHub (use the download icon).
+2. In Google Tag Manager, go to **Templates**.
+3. Click **New**.
+4. Open the three-dot menu and click **Import**.
+5. Select the downloaded template file.
+6. Click **Save**.
+
+## Setup
+
+### 1. Create a Tag ID variable
+
+Sign in to the [Picked Dashboard](https://dashboard.picked.app) and copy your project Tag ID. Save it as a constant variable in GTM (e.g. `Picked Tag ID`).
+
+![Creating a Picked Tag ID variable in GTM](/gtm/gtm-variable.png)
+
+### 2. Create an ecommerce data variable
+
+Create a **Data Layer Variable** with the variable name set to `ecommerce`. This captures the GA4 Enhanced Ecommerce data layer.
+
+![GA4 Enhanced Ecommerce data layer variable](/gtm/gtm-ecommerce-variable.png)
+
+### 3. Create event triggers
+
+Add a trigger for each ecommerce event you want to track (e.g. `add_to_cart`, `purchase`, `view_item`).
+
+![Event triggers for ecommerce tracking](/gtm/gtm-triggers.png)
+
+### 4. Create tags
+
+Create a new tag for each event, selecting the **Picked Ecommerce** tag template. Assign the matching trigger and configure the options below.
+
+![Tags using the Picked Ecommerce template](/gtm/gtm-tags.png)
+
+## Configuration options
+
+| Option | Description |
+| --- | --- |
+| **Tag ID** | Your Picked project Tag ID. Find it in the [Picked Dashboard](https://dashboard.picked.app). |
+| **Event** | The ecommerce event to track (e.g. `add_to_cart`, `purchase`). |
+| **Send ecommerce data** | Enable this to send GA4 Enhanced Ecommerce data to Picked. Should be enabled for all ecommerce events. |
+| **GA4 Enhanced Ecommerce Data** | The GTM variable containing GA4 ecommerce data. Use the data layer variable created in step 2. |
+| **Additional data** | Optional GTM variable for sending extra metadata with the event. |
+
+![Picked Ecommerce tag configuration](/gtm/gtm-tag.png)

package/dist/docs/tooling/index.md

@@ -0,0 +1,19 @@
+---
+layout: docs
+---
+
+# Tooling
+
+Build tools and developer utilities for working with Picked.
+
+## Vite Plugin
+
+The [`@picked/vite-plugin-picked`](/tooling/vite-plugin) package integrates Picked into your Vite-based project. It fetches your project configuration at build time and provides a local launcher for previewing experiences during development.
+
+[Get started with the Vite Plugin →](/tooling/vite-plugin)
+
+## Chrome Extension
+
+The [Picked Developer Tools](/tooling/chrome-extension) extension adds a dedicated panel to Chrome DevTools for inspecting and debugging your Picked integration on any page running the SDK.
+
+[Get started with the Chrome Extension →](/tooling/chrome-extension)