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

package/dist/docs/how-to/define-a-page-layout.md

@@ -0,0 +1,39 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to define a page layout
+
+This guide shows you how to define the shape of a page. A layout sets which fields a page
+can hold, and it holds no data itself.
+
+## Steps
+
+1. Open your workspace.
+2. Click **Pages** in the sidebar, then **Page Layouts**.
+3. Click **New model**.
+4. Set **Category** to **Page layout**.
+5. Enter a **Name** and a **Key**. The key is stable, and your SDK code and your API
+   calls both use it.
+6. Add your fields. Choose a type for each one.
+7. Click **Create model**.
+
+The category is fixed when you create the layout. You cannot change it later.
+
+## Make a field repeatable
+
+Turn on **repeatable** on any field. It then renders as a sortable list of values. Use it
+for a gallery, or for a list of features.
+
+## Group related fields
+
+Add a **Group** field to hold a set of fields under one key. Make the group repeatable to
+describe a list of objects, such as a list of feature cards.
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why the schema and the data
+  are separate.
+- [Page and step layouts](/reference/dashboard/content/layouts) — every field type.
+- [How to reuse a section](/how-to/reuse-a-section).

package/dist/docs/how-to/fill-and-publish-a-page.md

@@ -0,0 +1,50 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to fill and publish a page
+
+This guide shows you how to make a server-rendered Page and put content in it. You need a
+page layout first. See [How to define a page layout](/how-to/define-a-page-layout).
+
+## 1. Create the page
+
+1. Open your project.
+2. Choose a workspace.
+3. Click **Pages** in the sidebar.
+4. Click **New experience**.
+5. Choose the **Page** type.
+6. Choose a page layout.
+7. Click **Create page**.
+
+Picked makes a content entry and links it to the page on the first save.
+
+## 2. Fill in the content
+
+1. Open the **Properties** tab.
+2. Fill in each field. The inspector on the right edits the field that you choose.
+3. Watch the preview panel as the page fills in.
+
+## 3. Correct every error
+
+An invalid field shows an error next to it while you edit. Correct each one before you
+publish. Picked serves valid content only.
+
+## 4. Publish
+
+Publish the workspace to make the page live. See
+[How to publish a workspace](/how-to/publish-a-workspace).
+
+## Change the layout later
+
+Use the change-layout control on the **Settings** tab. When you unlink a layout, Picked
+separates the content entry from the page. It deletes no entry, but the page then has no
+content to render.
+
+## Related
+
+- [About pages and flows](/explanation/pages-and-flows) — when to choose a Page.
+- [Your first server-rendered page](/tutorials/first-server-rendered-page) — the whole
+  path, with the SDK.
+- [Pages](/reference/dashboard/content/pages) — the editor reference.

package/dist/docs/{gtm-template.md → how-to/install-the-gtm-template.md}

@@ -1,11 +1,12 @@
 ---
+type: how-to
 layout: docs
 ---
 
-# Template for Google Tag Manager
+# How to install the GTM template
 
-The Picked Ecommerce template for Google Tag Manager lets you track an ecommerce
-event and send it to Picked.
+This guide shows you how to track an ecommerce event in Google Tag Manager and send it to
+Picked. You need a GTM container and your Picked Tag ID.
 
 ## Automatic installation
 
@@ -76,3 +77,8 @@ the trigger that matches. Then set the options below.
 | **Additional data** | An optional GTM variable, for more metadata with the event. |
 
 ![The options on a Picked Ecommerce tag](/gtm/gtm-tag.png)
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works) — what Picked does with the
+  event.

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

@@ -0,0 +1,68 @@
+---
+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/client @picked/react effector effector-react
+```
+
+```bash [Svelte]
+npm install @picked/client @picked/svelte effector
+```
+
+:::
+
+## 2. Create and start the client
+
+:::code-group
+
+```tsx [React]
+import { createClient } from '@picked/client'
+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/client'
+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()
+```
+
+:::
+
+`start()` is idempotent. A second call changes nothing on a client that started already.
+
+## 3. 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.
+- [How to register a component](/how-to/register-a-component).

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

@@ -0,0 +1,56 @@
+---
+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
+```
+
+```bash [pnpm]
+pnpm add @picked/vite-plugin-picked
+```
+
+```bash [yarn]
+yarn add @picked/vite-plugin-picked
+```
+
+:::
+
+## 2. Add it to your config
+
+```typescript
+import { defineConfig } from 'vite'
+import { picked } from '@picked/vite-plugin-picked'
+
+export default defineConfig({
+  plugins: [
+    picked({
+      projectId: 'your-project-id',
+    }),
+  ],
+})
+```
+
+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.
+
+:::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.
+- [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

@@ -0,0 +1,34 @@
+---
+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. A person with no Picked account must
+create one first.
+
+## 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/preview-a-workspace.md

@@ -0,0 +1,28 @@
+---
+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

@@ -0,0 +1,30 @@
+---
+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

@@ -0,0 +1,101 @@
+---
+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** feature flag | No |
+| `client.features.listStore` | Every registered feature flag, each with an `isResolved` feature flag | 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
+
+:::code-group
+
+```tsx [React]
+import { useFeatureResult } from '@picked/react/hooks'
+
+function MyComponent() {
+  // { id, bucket }, or undefined until the feature flag resolves.
+  const result = useFeatureResult('my-feature')
+
+  return (
+    <div>
+      {result?.bucket === 'control' && <p>Control</p>}
+      {result?.bucket === 'variant-a' && <p>Variant A</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('my-feature')
+</script>
+
+{#if $result?.bucket === 'control'}
+  <p>Control</p>
+{:else if $result?.bucket === 'variant-a'}
+  <p>Variant A</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.
+:::
+
+## 3. Read it without a framework
+
+The event bus works with any framework, and with none:
+
+```ts
+import { createClient } from '@picked/client'
+
+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: 'control' }
+  }
+})
+```
+
+`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/register-a-component.md

@@ -0,0 +1,55 @@
+---
+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/client'
+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/client'
+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

@@ -0,0 +1,67 @@
+---
+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/client'
+
+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

@@ -0,0 +1,132 @@
+---
+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 } 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}>
+          <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.