@picked/client 0.0.1-dev.1789541668638 → 0.0.1-dev.1793756239746

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (213) hide show
  1. package/LICENSE +1 -0
  2. package/README.md +34 -158
  3. package/dist/.tsbuildinfo +1 -1
  4. package/dist/{api-C7q_7vxn.js → api-B5i4XuCs.js} +1 -1
  5. package/dist/api-DMYLC1At.cjs +1 -0
  6. package/dist/cjs/form/index.js +1 -1
  7. package/dist/cjs/index.js +2 -2
  8. package/dist/cjs/logic-engine.js +1 -0
  9. package/dist/cjs/plugins/dom-observer/index.js +1 -1
  10. package/dist/cjs/plugins/dynamic-experiences/index.js +1 -1
  11. package/dist/cjs/plugins/experience-browser-storage/index.js +1 -1
  12. package/dist/cjs/plugins/responses-browser-storage/index.js +1 -1
  13. package/dist/cjs/plugins/telemetry/index.js +1 -1
  14. package/dist/cjs/server/index.js +1 -1
  15. package/dist/cjs/storage.js +1 -0
  16. package/dist/dom-7g2LZCIp.cjs +1 -0
  17. package/dist/{dom-BqcToNL0.js → dom-v6ulxr_z.js} +1 -5
  18. package/dist/esm/form/index.js +5 -16
  19. package/dist/esm/index.js +465 -505
  20. package/dist/esm/logic-engine.js +208 -0
  21. package/dist/esm/plugins/dom-observer/index.js +1 -1
  22. package/dist/esm/plugins/dynamic-experiences/index.js +4 -4
  23. package/dist/esm/plugins/experience-browser-storage/index.js +12 -10
  24. package/dist/esm/plugins/responses-browser-storage/index.js +2 -6
  25. package/dist/esm/plugins/telemetry/index.js +26 -15
  26. package/dist/esm/preview/index.js +1 -2
  27. package/dist/esm/server/index.js +40 -36
  28. package/dist/esm/storage.js +1 -0
  29. package/dist/{experience-instance-B9S6Yf0N.js → experience-instance-4D6Yk-h0.js} +323 -260
  30. package/dist/experience-instance-D2FAkiPx.cjs +1 -0
  31. package/dist/plugin-CVLK5ZLV.cjs +1 -0
  32. package/dist/plugin-C_cLCzXK.js +256 -0
  33. package/dist/preview-channel-BMOEreho.cjs +1 -0
  34. package/dist/{preview-channel-CSr96XAo.js → preview-channel-CLXVoL_j.js} +2 -5
  35. package/dist/preview-unavailable-BAhTGDAp.cjs +1 -0
  36. package/dist/{version-CPKulHMH.js → preview-unavailable-OHRfSIId.js} +100 -61
  37. package/dist/provider-BFZgizAt.cjs +1 -0
  38. package/dist/provider-dD92LNPP.js +115 -0
  39. package/dist/{rules-logic-HesIUCu6.js → rules-logic-9hh8y_1b.js} +1 -1
  40. package/dist/rules-logic-VUbvWqdi.cjs +1 -0
  41. package/dist/types/data-source/preview-unavailable.d.ts +18 -0
  42. package/dist/types/data-source/preview-unavailable.d.ts.map +1 -0
  43. package/dist/types/data-source/provider.d.ts +5 -0
  44. package/dist/types/data-source/provider.d.ts.map +1 -1
  45. package/dist/types/data-source/request-observer.d.ts +21 -8
  46. package/dist/types/data-source/request-observer.d.ts.map +1 -1
  47. package/dist/types/entities/action/action.d.ts +94 -23
  48. package/dist/types/entities/action/action.d.ts.map +1 -1
  49. package/dist/types/entities/experience-instance/experience-instance.d.ts +14 -1
  50. package/dist/types/entities/experience-instance/experience-instance.d.ts.map +1 -1
  51. package/dist/types/exports.d.ts +1 -0
  52. package/dist/types/exports.d.ts.map +1 -1
  53. package/dist/types/index.d.ts +2 -2
  54. package/dist/types/index.d.ts.map +1 -1
  55. package/dist/types/lifecycle/rules-logic.d.ts.map +1 -1
  56. package/dist/types/logic-engine.d.ts +9 -0
  57. package/dist/types/logic-engine.d.ts.map +1 -1
  58. package/dist/types/picked.d.ts +38 -8
  59. package/dist/types/picked.d.ts.map +1 -1
  60. package/dist/types/plugins/dynamic-experiences/index.d.ts +1 -0
  61. package/dist/types/plugins/dynamic-experiences/index.d.ts.map +1 -1
  62. package/dist/types/plugins/dynamic-experiences/plugin.d.ts.map +1 -1
  63. package/dist/types/plugins/dynamic-experiences/types.d.ts +5 -2
  64. package/dist/types/plugins/dynamic-experiences/types.d.ts.map +1 -1
  65. package/dist/types/plugins/experience-browser-storage/plugin.d.ts.map +1 -1
  66. package/dist/types/plugins/telemetry/plugin.d.ts +2 -0
  67. package/dist/types/plugins/telemetry/plugin.d.ts.map +1 -1
  68. package/dist/types/schema-registry.d.ts +34 -0
  69. package/dist/types/schema-registry.d.ts.map +1 -1
  70. package/dist/types/server/serialize.d.ts +1 -0
  71. package/dist/types/server/serialize.d.ts.map +1 -1
  72. package/dist/types/storage.d.ts +6 -0
  73. package/dist/types/storage.d.ts.map +1 -0
  74. package/dist/types/typed-content.d.ts +14 -1
  75. package/dist/types/typed-content.d.ts.map +1 -1
  76. package/dist/types/utils/events.d.ts +4 -0
  77. package/dist/types/utils/events.d.ts.map +1 -1
  78. package/dist/types/utils/rules-logic.d.ts +3 -2
  79. package/dist/types/utils/rules-logic.d.ts.map +1 -1
  80. package/dist/types/utils/search-params.d.ts +20 -0
  81. package/dist/types/utils/search-params.d.ts.map +1 -1
  82. package/package.json +39 -13
  83. package/dist/api-Ctvh1qkk.cjs +0 -1
  84. package/dist/docs/_root.css +0 -101
  85. package/dist/docs/explanation/conditions-and-the-logic-engine.md +0 -94
  86. package/dist/docs/explanation/content-references.md +0 -99
  87. package/dist/docs/explanation/feature-flag-allocation.md +0 -218
  88. package/dist/docs/explanation/how-picked-works.md +0 -124
  89. package/dist/docs/explanation/how-pickedql-works.md +0 -76
  90. package/dist/docs/explanation/pages-and-flows.md +0 -64
  91. package/dist/docs/explanation/the-content-model.md +0 -87
  92. package/dist/docs/explanation/the-two-apis.md +0 -68
  93. package/dist/docs/explanation/why-server-side-rendering.md +0 -76
  94. package/dist/docs/explanation/workspaces-and-versions.md +0 -71
  95. package/dist/docs/how-to/add-a-step-field-or-action.md +0 -43
  96. package/dist/docs/how-to/analytics/index.md +0 -316
  97. package/dist/docs/how-to/archive-or-delete-a-workspace.md +0 -46
  98. package/dist/docs/how-to/authenticate-the-cli.md +0 -97
  99. package/dist/docs/how-to/authenticate-with-a-magic-link.md +0 -40
  100. package/dist/docs/how-to/authenticate-with-a-password.md +0 -51
  101. package/dist/docs/how-to/authenticate-with-an-api-key.md +0 -51
  102. package/dist/docs/how-to/authenticate-with-oauth.md +0 -40
  103. package/dist/docs/how-to/build-a-flow.md +0 -83
  104. package/dist/docs/how-to/connect-the-mcp-server.md +0 -38
  105. package/dist/docs/how-to/create-a-content-entry.md +0 -48
  106. package/dist/docs/how-to/create-a-project.md +0 -29
  107. package/dist/docs/how-to/create-an-experience.md +0 -42
  108. package/dist/docs/how-to/create-and-revoke-an-api-key.md +0 -42
  109. package/dist/docs/how-to/debug-with-the-chrome-extension.md +0 -57
  110. package/dist/docs/how-to/define-a-page-layout.md +0 -46
  111. package/dist/docs/how-to/fill-and-publish-a-page.md +0 -66
  112. package/dist/docs/how-to/install-the-gtm-template.md +0 -84
  113. package/dist/docs/how-to/install-the-sdk.md +0 -93
  114. package/dist/docs/how-to/install-the-vite-plugin.md +0 -69
  115. package/dist/docs/how-to/invite-and-remove-members.md +0 -35
  116. package/dist/docs/how-to/point-one-entry-at-another.md +0 -61
  117. package/dist/docs/how-to/preview-a-workspace.md +0 -28
  118. package/dist/docs/how-to/publish-a-workspace.md +0 -30
  119. package/dist/docs/how-to/read-a-feature-flag.md +0 -113
  120. package/dist/docs/how-to/read-a-referenced-entry.md +0 -109
  121. package/dist/docs/how-to/register-a-component.md +0 -55
  122. package/dist/docs/how-to/register-an-action-handler.md +0 -67
  123. package/dist/docs/how-to/render-a-step-form.md +0 -131
  124. package/dist/docs/how-to/render-an-unpublished-preview.md +0 -41
  125. package/dist/docs/how-to/reuse-a-section.md +0 -53
  126. package/dist/docs/how-to/reuse-a-step-field-or-action.md +0 -28
  127. package/dist/docs/how-to/roll-back-a-published-version.md +0 -26
  128. package/dist/docs/how-to/run-an-ab-test.md +0 -49
  129. package/dist/docs/how-to/run-code-on-a-form-submission.md +0 -125
  130. package/dist/docs/how-to/server-render-a-page.md +0 -81
  131. package/dist/docs/how-to/set-a-content-security-policy.md +0 -32
  132. package/dist/docs/how-to/set-up-mfa.md +0 -69
  133. package/dist/docs/how-to/switch-workspaces.md +0 -122
  134. package/dist/docs/how-to/upload-and-use-an-asset.mdx +0 -73
  135. package/dist/docs/how-to/validate-a-field.md +0 -52
  136. package/dist/docs/how-to/write-a-condition.md +0 -45
  137. package/dist/docs/how-to/write-a-predicate.md +0 -60
  138. package/dist/docs/index.md +0 -59
  139. package/dist/docs/reference/dashboard/actions.mdx +0 -53
  140. package/dist/docs/reference/dashboard/api-keys.mdx +0 -38
  141. package/dist/docs/reference/dashboard/conditions.mdx +0 -42
  142. package/dist/docs/reference/dashboard/content/asset-library.mdx +0 -63
  143. package/dist/docs/reference/dashboard/content/blocks.mdx +0 -57
  144. package/dist/docs/reference/dashboard/content/content-entries.mdx +0 -95
  145. package/dist/docs/reference/dashboard/content/models.mdx +0 -108
  146. package/dist/docs/reference/dashboard/content/pages.mdx +0 -61
  147. package/dist/docs/reference/dashboard/experiences.mdx +0 -51
  148. package/dist/docs/reference/dashboard/features.mdx +0 -154
  149. package/dist/docs/reference/dashboard/fields.mdx +0 -106
  150. package/dist/docs/reference/dashboard/flow-builder/canvas.mdx +0 -58
  151. package/dist/docs/reference/dashboard/flow-builder/condition-builder.md +0 -57
  152. package/dist/docs/reference/dashboard/flow-builder/keyboard-shortcuts.md +0 -72
  153. package/dist/docs/reference/dashboard/flow-builder/nodes.md +0 -63
  154. package/dist/docs/reference/dashboard/projects.mdx +0 -44
  155. package/dist/docs/reference/dashboard/reports.mdx +0 -43
  156. package/dist/docs/reference/dashboard/steps.mdx +0 -37
  157. package/dist/docs/reference/dashboard/team-management.md +0 -29
  158. package/dist/docs/reference/dashboard/workspace-versioning.mdx +0 -30
  159. package/dist/docs/reference/dashboard/workspaces.mdx +0 -76
  160. package/dist/docs/reference/delivery-api/experience-content.md +0 -152
  161. package/dist/docs/reference/delivery-api/index.md +0 -45
  162. package/dist/docs/reference/delivery-api/preview-caching-crawling.md +0 -79
  163. package/dist/docs/reference/delivery-api/project-config.md +0 -65
  164. package/dist/docs/reference/delivery-api/workspace-schema.md +0 -85
  165. package/dist/docs/reference/glossary.md +0 -181
  166. package/dist/docs/reference/management-api/authentication.md +0 -74
  167. package/dist/docs/reference/management-api/authorization-and-scopes.md +0 -285
  168. package/dist/docs/reference/management-api/error-handling.md +0 -233
  169. package/dist/docs/reference/management-api/pagination.md +0 -192
  170. package/dist/docs/reference/pickedql/data-sources.md +0 -174
  171. package/dist/docs/reference/pickedql/dimensions.md +0 -103
  172. package/dist/docs/reference/pickedql/filtering.md +0 -64
  173. package/dist/docs/reference/pickedql/index.md +0 -18
  174. package/dist/docs/reference/pickedql/schema.md +0 -172
  175. package/dist/docs/reference/pickedql/virtual-functions.md +0 -248
  176. package/dist/docs/reference/sdk/actions.md +0 -30
  177. package/dist/docs/reference/sdk/analytics-events.md +0 -445
  178. package/dist/docs/reference/sdk/conditions.md +0 -147
  179. package/dist/docs/reference/sdk/content-security-policy.md +0 -21
  180. package/dist/docs/reference/sdk/content.md +0 -213
  181. package/dist/docs/reference/sdk/experiences.md +0 -51
  182. package/dist/docs/reference/sdk/features.md +0 -256
  183. package/dist/docs/reference/sdk/fields.md +0 -255
  184. package/dist/docs/reference/sdk/index.md +0 -68
  185. package/dist/docs/reference/sdk/plugins/create-experience.md +0 -123
  186. package/dist/docs/reference/sdk/plugins/dynamic-experiences.md +0 -74
  187. package/dist/docs/reference/sdk/plugins/index.md +0 -29
  188. package/dist/docs/reference/sdk/plugins/window-object.md +0 -25
  189. package/dist/docs/reference/sdk/predicates.md +0 -43
  190. package/dist/docs/reference/sdk/ssr/index.md +0 -33
  191. package/dist/docs/reference/sdk/ssr/rendering-and-hydration.md +0 -103
  192. package/dist/docs/reference/sdk/ssr/serialize.md +0 -80
  193. package/dist/docs/reference/sdk/ssr/slots-and-placements.md +0 -59
  194. package/dist/docs/reference/sdk/steps.md +0 -86
  195. package/dist/docs/reference/sdk/type-generation.md +0 -196
  196. package/dist/docs/reference/tools/chrome-extension.md +0 -16
  197. package/dist/docs/reference/tools/cli.md +0 -146
  198. package/dist/docs/reference/tools/image-optimisation-service.md +0 -104
  199. package/dist/docs/reference/tools/mcp.md +0 -90
  200. package/dist/docs/reference/tools/vite-plugin.md +0 -163
  201. package/dist/docs/tutorials/first-api-call.md +0 -228
  202. package/dist/docs/tutorials/first-experience-in-the-dashboard.mdx +0 -143
  203. package/dist/docs/tutorials/first-experience.mdx +0 -254
  204. package/dist/docs/tutorials/first-server-rendered-page.mdx +0 -186
  205. package/dist/dom-DlLH3FxV.cjs +0 -1
  206. package/dist/experience-instance-D8rOg6We.cjs +0 -1
  207. package/dist/plugin-ChafFq6S.js +0 -194
  208. package/dist/plugin-Dn25Gffy.cjs +0 -1
  209. package/dist/preview-channel-Cx0e6fye.cjs +0 -1
  210. package/dist/provider-B8wvmeC8.js +0 -98
  211. package/dist/provider-BBLlQOjV.cjs +0 -1
  212. package/dist/rules-logic-CGZIYgAI.cjs +0 -1
  213. package/dist/version-CLjPfmxk.cjs +0 -1
@@ -1,55 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to register a component
7
-
8
- This guide shows you how to connect a component in your application to an experience in
9
- the dashboard.
10
-
11
- ## Steps
12
-
13
- 1. Wrap your component with the adapter for your framework.
14
- 2. Pass it in the `components` object of `createClient()`.
15
- 3. Use the same key as the component name of the experience.
16
-
17
- :::code-group
18
-
19
- ```tsx [React]
20
- import { createClient } from 'picked'
21
- import { adaptReactComponent } from '@picked/react'
22
- import { MyWidget } from './MyWidget'
23
-
24
- const picked = createClient({
25
- projectId: 'your-project-id',
26
- components: {
27
- MyWidget: adaptReactComponent(MyWidget),
28
- },
29
- })
30
- ```
31
-
32
- ```ts [Svelte]
33
- import { createClient } from 'picked'
34
- import { adaptSvelteComponent } from '@picked/svelte'
35
- import MyWidget from './MyWidget.svelte'
36
-
37
- const picked = createClient({
38
- projectId: 'your-project-id',
39
- components: {
40
- MyWidget: adaptSvelteComponent(MyWidget),
41
- },
42
- })
43
- ```
44
-
45
- :::
46
-
47
- :::warning
48
- `components` takes an adapted component. A plain React or Svelte component does not work
49
- without `adaptReactComponent` or `adaptSvelteComponent`.
50
- :::
51
-
52
- ## Related
53
-
54
- - [SDK experiences](/reference/sdk/experiences) — the experience shape.
55
- - [How to install the SDK](/how-to/install-the-sdk).
@@ -1,67 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to register an action handler
7
-
8
- This guide shows you how to connect an action node in a flow to a function in your
9
- application. You need an action in your project first, with a key. See
10
- [Actions](/reference/dashboard/actions).
11
-
12
- ## 1. Register the handler
13
-
14
- Pass an `actions` object to `createClient()`. Each key must match an action key from the
15
- dashboard:
16
-
17
- ```ts
18
- import { createClient } from 'picked'
19
-
20
- const picked = createClient({
21
- projectId: 'your-project-id',
22
- actions: {
23
- 'track-signup': () => {
24
- analytics.track('signup_completed')
25
- },
26
- notify: (params) => {
27
- sendNotification(params)
28
- },
29
- },
30
- })
31
- ```
32
-
33
- The SDK calls the function that matches when the flow reaches the action node.
34
-
35
- ## 2. Throw only for a true error
36
-
37
- The flow takes the failure branch when your handler throws or its promise rejects. Throw
38
- when the request itself did not complete:
39
-
40
- ```ts
41
- 'check-eligibility': async () => {
42
- const response = await fetch('/api/eligibility')
43
- // Throw only when the request itself fails. That takes the failure branch.
44
- if (!response.ok) throw new Error('Eligibility request failed')
45
- }
46
- ```
47
-
48
- ## 3. Record a negative answer as a response
49
-
50
- A valid negative result is not a failure. An endpoint can answer `200` with a "no". Store
51
- that value as a response and branch on it with a condition instead:
52
-
53
- ```ts
54
- 'check-serviced-area': async ({ client, responses }) => {
55
- const postcode = responses.find((r) => r.fieldKey === 'postcode')?.value
56
- const { serviced } = await fetch(`/api/serviced?postcode=${postcode}`).then((r) => r.json())
57
- // Store the outcome as a response. A later condition then takes the branch.
58
- client.responses.register('is-serviced', serviced)
59
- }
60
- ```
61
-
62
- ## Related
63
-
64
- - [About how Picked works](/explanation/how-picked-works#how-an-action-decides-which-way-to-go)
65
- — why a returned `false` is a success.
66
- - [SDK actions](/reference/sdk/actions) — what the handler receives and returns.
67
- - [Actions](/reference/dashboard/actions) — the dashboard options.
@@ -1,131 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to render a step form
7
-
8
- This guide shows you how to render the fields of the active step and let a visitor submit
9
- them.
10
-
11
- ## 1. Put the steps in a router
12
-
13
- `StepRouter` watches the step state and activates the `Step` whose `id` matches.
14
-
15
- :::code-group
16
-
17
- ```tsx [React]
18
- import { StepRouter, Step } from '@picked/react/router'
19
-
20
- function MyExperience() {
21
- return (
22
- <StepRouter>
23
- <Step id="welcome">
24
- <WelcomeScreen />
25
- </Step>
26
- <Step id="contact">
27
- <ContactForm />
28
- </Step>
29
- </StepRouter>
30
- )
31
- }
32
- ```
33
-
34
- ```svelte [Svelte]
35
- <script lang="ts">
36
- import { StepRouter, Step } from '@picked/svelte/router'
37
- </script>
38
-
39
- <StepRouter>
40
- <Step id="welcome">
41
- <WelcomeScreen />
42
- </Step>
43
- <Step id="contact">
44
- <ContactForm />
45
- </Step>
46
- </StepRouter>
47
- ```
48
-
49
- :::
50
-
51
- :::note
52
- A router must hold every Step, even when there is only one Step.
53
- :::
54
-
55
- ## 2. Render the fields
56
-
57
- Bind `form.props` to your `<form>` element and map over the fields.
58
-
59
- :::code-group
60
-
61
- ```tsx [React]
62
- import { useStep, useStoreGlobal } from '@picked/react/hooks'
63
-
64
- function StepForm() {
65
- const { fields, form } = useStep()
66
- const currentFields = useStoreGlobal(fields)
67
- const isSubmitting = useStoreGlobal(form.submitting)
68
-
69
- return (
70
- <form {...form.props}>
71
- {currentFields.map((field) => (
72
- <div key={field.id}>
73
- <label htmlFor={field.id}>{field.label}</label>
74
- <input
75
- id={field.id}
76
- name={field.id}
77
- value={field.value ?? ''}
78
- onChange={field.onChange}
79
- onBlur={field.onBlur}
80
- />
81
- {field.error && field.touched && <p className="error">{field.error.userMessage}</p>}
82
- </div>
83
- ))}
84
- <button type="submit" disabled={isSubmitting}>Continue</button>
85
- </form>
86
- )
87
- }
88
- ```
89
-
90
- ```svelte [Svelte]
91
- <script lang="ts">
92
- import { getStep } from '@picked/svelte/hooks'
93
-
94
- const { fields, form } = getStep()
95
- const isSubmitting = form.submitting
96
- </script>
97
-
98
- <form {...form.props}>
99
- {#each $fields as field}
100
- <div>
101
- <label for={field.id}>{field.label}</label>
102
- <input
103
- id={field.id}
104
- name={field.id}
105
- value={field.value ?? ''}
106
- onchange={field.onChange}
107
- onblur={field.onBlur}
108
- />
109
- {#if field.error && field.touched}
110
- <p class="error">{field.error.userMessage}</p>
111
- {/if}
112
- </div>
113
- {/each}
114
- <button type="submit" disabled={$isSubmitting}>Continue</button>
115
- </form>
116
- ```
117
-
118
- :::
119
-
120
- The SDK checks a field on blur, and not while the visitor types.
121
-
122
- ## 3. Load a large step lazily
123
-
124
- Pass a dynamic import to the `component` prop of `<Step>`. The SDK does not load the
125
- content until that step becomes active.
126
-
127
- ## Related
128
-
129
- - [How to run code on a form submission](/how-to/run-code-on-a-form-submission) — the
130
- callbacks.
131
- - [SDK steps](/reference/sdk/steps) — the `StepContext` shape.
@@ -1,41 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to render an unpublished preview
7
-
8
- This guide shows you how to render draft content on your server. Your server cannot read
9
- the query string of the browser, so you must pass the token yourself.
10
-
11
- ## 1. Get the token
12
-
13
- The management API holds the preview token of a workspace in the `previewToken` field. The
14
- preview action in the dashboard also makes one for you.
15
-
16
- ## 2. Read the config with the token
17
-
18
- ```bash
19
- curl "https://api.picked.app/api/v1/projects/proj_123?preview_token=<token>"
20
- ```
21
-
22
- A preview response returns `versionId: null`. An invalid token returns `401`.
23
-
24
- ## 3. Pass the same token to `serialize()`
25
-
26
- ```ts
27
- const snapshot = await serialize(client, {
28
- projectConfig,
29
- attributes: { location: { pathname: '/promo' } },
30
- previewToken,
31
- })
32
- ```
33
-
34
- Use the same token for both requests. The configuration and the content then come from the same
35
- preview.
36
-
37
- ## Related
38
-
39
- - [About the two APIs](/explanation/the-two-apis) — how a preview stays out of the search
40
- index.
41
- - [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).
@@ -1,53 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to reuse a section
7
-
8
- This guide shows you how to define a common structure one time and use it in more than
9
- one Model.
10
-
11
- ## 1. Create the section
12
-
13
- 1. Click **Pages** in the sidebar.
14
- 2. Click **Page Sections**.
15
- 3. Click **New block**.
16
- 4. Enter a **Name** and a **Key**.
17
- 5. Add your fields.
18
- 6. Click **Create block**.
19
-
20
- The **Category** is **Section** already, because you opened the list from **Page
21
- Sections**.
22
-
23
- ## 2. Accept the section in a Model
24
-
25
- 1. Open a page layout or a step layout.
26
- 2. Add a **Page Sections** field to the schema.
27
- 3. Click **Save**.
28
-
29
- The field now accepts any Block of the Section category. Make the field repeatable to
30
- build a page from a list of sections.
31
-
32
- If you want one section at a fixed place instead of a list, add a **Content block** field.
33
- Set its **Block category** to the **Section** category.
34
-
35
- ## 3. Choose the section in an entry
36
-
37
- 1. Open a content entry that uses the Model.
38
- 2. Find the field that you added.
39
- 3. Choose your Block.
40
- 4. Fill in the fields of the Block.
41
- 5. Click **Save**.
42
-
43
- :::warning
44
- An edit to a Block does not migrate the entries that use it. Check each affected content
45
- entry again, and correct every field error before you publish.
46
- :::
47
-
48
- ## Related
49
-
50
- - [About the content model](/explanation/the-content-model) — why a schema change does not
51
- migrate your data.
52
- - [Blocks](/reference/dashboard/content/blocks) — the reference.
53
- - [Models](/reference/dashboard/content/models) — every field type.
@@ -1,28 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to reuse a step, a field, or an action
7
-
8
- This guide shows you how to use one step, field, action, or condition in more than one
9
- flow. All four belong to the project, and not to the experience that you made them in.
10
-
11
- ## Steps
12
-
13
- 1. Open the flow builder for the second experience.
14
- 2. Find the step, the action, or the condition in the library on the left.
15
- 3. Drag it onto the canvas, or onto a step node for a field.
16
-
17
- The same one now appears in both flows.
18
-
19
- :::warning
20
- A change to the options applies at every place that uses it. Check the other flows before
21
- you change a shared step, field, action, or condition.
22
- :::
23
-
24
- ## Related
25
-
26
- - [Steps](/reference/dashboard/steps) — the step options.
27
- - [Fields](/reference/dashboard/fields) — the field options.
28
- - [Actions](/reference/dashboard/actions) — the action options.
@@ -1,26 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to roll back a published version
7
-
8
- This guide shows you how to make an earlier published version live again. Your current
9
- draft does not change.
10
-
11
- ## Steps
12
-
13
- 1. Open **Publish history** from the project sidebar.
14
- 2. Find the version that you want to restore.
15
- 3. Click **Restore**.
16
- 4. Read the diff preview. It compares the current live version against the one that you
17
- chose.
18
- 5. Click **Restore this version** to confirm.
19
-
20
- The restored version is live immediately.
21
-
22
- ## Related
23
-
24
- - [About workspaces and versions](/explanation/workspaces-and-versions) — why a roll-back
25
- changes no data.
26
- - [Publish history](/reference/dashboard/workspace-versioning) — the version list.
@@ -1,49 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to run an A/B test
7
-
8
- This guide shows you how to split your traffic with a feature flag and read the result in
9
- your application.
10
-
11
- Read [About feature flag allocation](/explanation/feature-flag-allocation) first. The
12
- point at which you read the feature flag decides when a visitor enters the test.
13
-
14
- ## 1. Create the feature flag
15
-
16
- 1. Open your project.
17
- 2. Click **Feature flags** in the sidebar.
18
- 3. Click **New feature flag**.
19
- 4. Enter a name.
20
- 5. Click **Create feature flag**.
21
-
22
- You cannot change the key after you create the feature flag.
23
-
24
- ## 2. Set the allocation
25
-
26
- Open the detail page of the feature flag and set these controls:
27
-
28
- 1. Turn **Enabled** on. A feature flag that is off allocates nobody.
29
- 2. Set **Weight** to the percentage of visitors that you want in the test.
30
- 3. Enter a **Description** that says what the feature flag tests.
31
-
32
- ## 3. Read the feature flag in your application
33
-
34
- See [How to read a feature flag](/how-to/read-a-feature-flag). Read it at the point where
35
- the decision matters, and not at startup.
36
-
37
- ## 4. Change the weight later
38
-
39
- 1. Change **Weight** on the detail page.
40
- 2. Increment the version.
41
-
42
- The new weight then applies to a visitor with a cached decision. Leave the version as it
43
- is to apply the new weight only to a visitor who is not allocated yet.
44
-
45
- ## Related
46
-
47
- - [About feature flag allocation](/explanation/feature-flag-allocation) — why two feature
48
- flags at the same weight give four groups, not two.
49
- - [Feature flags](/reference/dashboard/features) — the controls.
@@ -1,125 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to run code on a form submission
7
-
8
- This guide shows you how to act on a step submission. Pass your callbacks to `useStep()`
9
- in React, or to `getStep()` in Svelte.
10
-
11
- ## What the SDK does on submit
12
-
13
- 1. It collects the field values from the HTML form.
14
- 2. It runs each `onBeforeSubmit` callback, one after another.
15
- 3. It checks each required field and each validation rule.
16
- 4. It commits the responses to the experience state.
17
- 5. It fires `form_submit_success` or `form_submit_error` on the event bus.
18
- 6. It runs your `onSuccess` or `onError` callback.
19
- 7. It moves to the next step.
20
-
21
- ## Change the data before it is stored
22
-
23
- :::code-group
24
-
25
- ```tsx [React]
26
- const { form } = useStep({
27
- onBeforeSubmit: async (data) => ({
28
- ...data,
29
- 'email-address': String(data['email-address']).toLowerCase(),
30
- }),
31
- })
32
- ```
33
-
34
- ```svelte [Svelte]
35
- <script lang="ts">
36
- const { form } = getStep({
37
- onBeforeSubmit: async (data) => ({
38
- ...data,
39
- 'email-address': String(data['email-address']).toLowerCase(),
40
- }),
41
- })
42
- </script>
43
- ```
44
-
45
- :::
46
-
47
- :::warning
48
- An `onBeforeSubmit` callback that throws aborts the submit before the SDK commits
49
- anything, and the step does not advance. Use it for a transform and for a check. Put a
50
- side effect, such as an analytics call, in `onSuccess`.
51
- :::
52
-
53
- ## Act on the outcome
54
-
55
- :::code-group
56
-
57
- ```tsx [React]
58
- const { form } = useStep({
59
- onSuccess: ({ data }) => analytics.track('lead_captured', data),
60
- onError: (errors) => console.error('Validation errors:', errors),
61
- })
62
- ```
63
-
64
- ```svelte [Svelte]
65
- <script lang="ts">
66
- const { form } = getStep({
67
- onSuccess: ({ data }) => analytics.track('lead_captured', data),
68
- onError: (errors) => console.error('Validation errors:', errors),
69
- })
70
- </script>
71
- ```
72
-
73
- :::
74
-
75
- A callback belongs to the component that passes it, and the SDK releases it when that
76
- component unmounts. An `onSuccess` callback that throws cannot stop the flow. The SDK
77
- reports the failure as `form_submit_callback_error`.
78
-
79
- ## Choose the next step yourself
80
-
81
- Call `stopNavigation()` inside `onSuccess`, then move where you want:
82
-
83
- :::code-group
84
-
85
- ```tsx [React]
86
- const experience = useExperience()
87
-
88
- const { form } = useStep({
89
- onSuccess: ({ data, stopNavigation }) => {
90
- stopNavigation()
91
- if (data['plan-type'] === 'enterprise') {
92
- experience.goToStepById('enterprise-contact')
93
- } else {
94
- experience.goToNextStep()
95
- }
96
- },
97
- })
98
- ```
99
-
100
- ```svelte [Svelte]
101
- <script lang="ts">
102
- const experience = getExperience()
103
-
104
- const { form } = getStep({
105
- onSuccess: ({ data, stopNavigation }) => {
106
- stopNavigation()
107
- if (data['plan-type'] === 'enterprise') {
108
- experience.goToStepById('enterprise-contact')
109
- } else {
110
- experience.goToNextStep()
111
- }
112
- },
113
- })
114
- </script>
115
- ```
116
-
117
- :::
118
-
119
- `goToStepById()` takes a step `id`. `goToStepByKey()` takes the key of the step. When no
120
- step matches, the call does nothing.
121
-
122
- ## Related
123
-
124
- - [How to render a step form](/how-to/render-a-step-form).
125
- - [SDK steps](/reference/sdk/steps) — the `form` object.
@@ -1,81 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to server-render a page
7
-
8
- This guide shows you how to render a Picked Page on your server and hydrate it in the
9
- browser. You need a published Page and a server that renders React or Svelte.
10
-
11
- ## 1. Make the snapshot
12
-
13
- Create one client for each request, then call `serialize()`:
14
-
15
- ```ts
16
- import { createClient } from 'picked'
17
- import { serialize } from '@picked/client/server'
18
-
19
- const client = createClient(options)
20
-
21
- const snapshot = await serialize(client, {
22
- projectConfig,
23
- attributes: { location: { pathname: url.pathname } },
24
- })
25
- ```
26
-
27
- :::warning
28
- Give `serialize()` one client for each request. It does not support two calls at the same
29
- time on one client.
30
- :::
31
-
32
- ## 2. Embed the snapshot
33
-
34
- ```ts
35
- const html = `
36
- <div id="root">${appHtml}</div>
37
- <script>window.__PICKED__ = ${JSON.stringify(snapshot)}</script>
38
- `
39
- ```
40
-
41
- ## 3. Seed the client and render the slot
42
-
43
- :::code-group
44
-
45
- ```tsx [React]
46
- import { PickedProvider, ExperienceSlot } from '@picked/react'
47
-
48
- export function Page({ snapshot }) {
49
- return (
50
- <PickedProvider options={options} snapshot={snapshot}>
51
- <ExperienceSlot name="page" />
52
- </PickedProvider>
53
- )
54
- }
55
- ```
56
-
57
- ```svelte [Svelte]
58
- <script lang="ts">
59
- import { ExperienceSlot, setPickedContext } from '@picked/svelte'
60
-
61
- const { snapshot } = $props()
62
- setPickedContext({ options, snapshot })
63
- </script>
64
-
65
- <ExperienceSlot name="page" />
66
- ```
67
-
68
- :::
69
-
70
- The provider seeds the client at once, so the server HTML and the first paint match.
71
-
72
- ## 4. Point the experience at the slot
73
-
74
- Set the target selector of your Page experience to `.picked-slot-page`, then publish.
75
-
76
- ## Related
77
-
78
- - [About server-side rendering](/explanation/why-server-side-rendering) — why the
79
- snapshot carries condition results.
80
- - [Server snapshot](/reference/sdk/ssr/serialize) — every parameter.
81
- - [Your first server-rendered page](/tutorials/first-server-rendered-page).
@@ -1,32 +0,0 @@
1
- ---
2
- type: how-to
3
- layout: docs
4
- ---
5
-
6
- # How to set a Content Security Policy
7
-
8
- This guide shows you how to let the Picked SDK load its resources under a CSP.
9
-
10
- ## Steps
11
-
12
- Add the Picked domains to your policy.
13
-
14
- As an HTTP header:
15
-
16
- ```
17
- Content-Security-Policy: connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;
18
- ```
19
-
20
- Or as a `<meta>` tag:
21
-
22
- ```html
23
- <meta
24
- http-equiv="Content-Security-Policy"
25
- content="connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;"
26
- />
27
- ```
28
-
29
- ## Related
30
-
31
- - [Content Security Policy](/reference/sdk/content-security-policy) — what each domain is
32
- for.