@picked/client 0.0.70 → 0.0.71-next.2

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 (249) hide show
  1. package/dist/.tsbuildinfo +1 -0
  2. package/dist/api-B0ydpQBE.js +38 -0
  3. package/dist/api-CObostrU.cjs +1 -0
  4. package/dist/cjs/form/index.js +1 -1
  5. package/dist/cjs/index.js +2 -2
  6. package/dist/cjs/plugins/dom-observer/index.js +1 -1
  7. package/dist/cjs/plugins/dynamic-experiences/index.js +1 -1
  8. package/dist/cjs/server/index.js +1 -1
  9. package/dist/docs/explanation/conditions-and-the-logic-engine.md +94 -0
  10. package/dist/docs/explanation/feature-flag-allocation.md +176 -0
  11. package/dist/docs/explanation/how-picked-works.md +102 -0
  12. package/dist/docs/explanation/how-pickedql-works.md +76 -0
  13. package/dist/docs/explanation/pages-and-flows.md +64 -0
  14. package/dist/docs/explanation/the-content-model.md +77 -0
  15. package/dist/docs/explanation/the-two-apis.md +68 -0
  16. package/dist/docs/explanation/why-server-side-rendering.md +76 -0
  17. package/dist/docs/explanation/workspaces-and-versions.md +71 -0
  18. package/dist/docs/how-to/add-a-step-field-or-action.md +43 -0
  19. package/dist/docs/{pickedql/examples.md → how-to/analytics/index.md} +19 -6
  20. package/dist/docs/how-to/archive-or-delete-a-workspace.md +46 -0
  21. package/dist/docs/how-to/authenticate-with-a-magic-link.md +40 -0
  22. package/dist/docs/how-to/authenticate-with-a-password.md +51 -0
  23. package/dist/docs/how-to/authenticate-with-an-api-key.md +51 -0
  24. package/dist/docs/how-to/authenticate-with-oauth.md +40 -0
  25. package/dist/docs/{flow-builder/building-flows.md → how-to/build-a-flow.md} +13 -9
  26. package/dist/docs/how-to/connect-the-mcp-server.md +38 -0
  27. package/dist/docs/how-to/create-a-project.md +29 -0
  28. package/dist/docs/how-to/create-an-experience.md +42 -0
  29. package/dist/docs/how-to/create-and-revoke-an-api-key.md +37 -0
  30. package/dist/docs/how-to/debug-with-the-chrome-extension.md +57 -0
  31. package/dist/docs/how-to/define-a-page-layout.md +39 -0
  32. package/dist/docs/how-to/fill-and-publish-a-page.md +50 -0
  33. package/dist/docs/{gtm-template.md → how-to/install-the-gtm-template.md} +9 -3
  34. package/dist/docs/how-to/install-the-sdk.md +68 -0
  35. package/dist/docs/how-to/install-the-vite-plugin.md +56 -0
  36. package/dist/docs/how-to/invite-and-remove-members.md +34 -0
  37. package/dist/docs/how-to/preview-a-workspace.md +28 -0
  38. package/dist/docs/how-to/publish-a-workspace.md +30 -0
  39. package/dist/docs/how-to/read-a-feature-flag.md +101 -0
  40. package/dist/docs/how-to/register-a-component.md +55 -0
  41. package/dist/docs/how-to/register-an-action-handler.md +67 -0
  42. package/dist/docs/how-to/render-a-step-form.md +132 -0
  43. package/dist/docs/how-to/render-an-unpublished-preview.md +41 -0
  44. package/dist/docs/how-to/reuse-a-section.md +37 -0
  45. package/dist/docs/how-to/reuse-a-step-field-or-action.md +28 -0
  46. package/dist/docs/how-to/roll-back-a-published-version.md +26 -0
  47. package/dist/docs/how-to/run-an-ab-test.md +49 -0
  48. package/dist/docs/how-to/run-code-on-a-form-submission.md +125 -0
  49. package/dist/docs/how-to/server-render-a-page.md +81 -0
  50. package/dist/docs/how-to/set-a-content-security-policy.md +32 -0
  51. package/dist/docs/how-to/set-up-mfa.md +69 -0
  52. package/dist/docs/how-to/upload-and-use-an-asset.mdx +73 -0
  53. package/dist/docs/how-to/validate-a-field.md +52 -0
  54. package/dist/docs/how-to/write-a-condition.md +45 -0
  55. package/dist/docs/how-to/write-a-predicate.md +60 -0
  56. package/dist/docs/index.md +41 -70
  57. package/dist/docs/reference/dashboard/actions.mdx +53 -0
  58. package/dist/docs/{api-keys.mdx → reference/dashboard/api-keys.mdx} +7 -15
  59. package/dist/docs/reference/dashboard/conditions.mdx +42 -0
  60. package/dist/docs/reference/dashboard/content/asset-library.mdx +63 -0
  61. package/dist/docs/{content → reference/dashboard/content}/content-entries.mdx +11 -3
  62. package/dist/docs/{content → reference/dashboard/content}/layouts.mdx +11 -35
  63. package/dist/docs/reference/dashboard/content/pages.mdx +35 -0
  64. package/dist/docs/reference/dashboard/content/sections.mdx +28 -0
  65. package/dist/docs/{experiences.mdx → reference/dashboard/experiences.mdx} +9 -16
  66. package/dist/docs/{features.mdx → reference/dashboard/features.mdx} +26 -41
  67. package/dist/docs/{fields.mdx → reference/dashboard/fields.mdx} +26 -20
  68. package/dist/docs/{flow-builder/overview.mdx → reference/dashboard/flow-builder/canvas.mdx} +8 -13
  69. package/dist/docs/{flow-builder → reference/dashboard/flow-builder}/condition-builder.md +5 -13
  70. package/dist/docs/{flow-builder → reference/dashboard/flow-builder}/keyboard-shortcuts.md +7 -1
  71. package/dist/docs/{flow-builder → reference/dashboard/flow-builder}/nodes.md +10 -3
  72. package/dist/docs/reference/dashboard/projects.mdx +44 -0
  73. package/dist/docs/reference/dashboard/reports.mdx +43 -0
  74. package/dist/docs/reference/dashboard/steps.mdx +37 -0
  75. package/dist/docs/{team-management.md → reference/dashboard/team-management.md} +5 -22
  76. package/dist/docs/{workspace-versioning.mdx → reference/dashboard/workspace-versioning.mdx} +6 -10
  77. package/dist/docs/reference/dashboard/workspaces.mdx +76 -0
  78. package/dist/docs/{delivery-api → reference/delivery-api}/experience-content.md +11 -4
  79. package/dist/docs/reference/delivery-api/index.md +45 -0
  80. package/dist/docs/{delivery-api → reference/delivery-api}/preview-caching-crawling.md +12 -5
  81. package/dist/docs/{delivery-api → reference/delivery-api}/project-config.md +11 -4
  82. package/dist/docs/reference/glossary.md +173 -0
  83. package/dist/docs/reference/management-api/authentication.md +74 -0
  84. package/dist/docs/{api → reference/management-api}/authorization-and-scopes.md +10 -3
  85. package/dist/docs/{api → reference/management-api}/error-handling.md +9 -3
  86. package/dist/docs/{api → reference/management-api}/pagination.md +6 -0
  87. package/dist/docs/{pickedql → reference/pickedql}/data-sources.md +16 -9
  88. package/dist/docs/{pickedql → reference/pickedql}/dimensions.md +7 -0
  89. package/dist/docs/{pickedql → reference/pickedql}/filtering.md +7 -0
  90. package/dist/docs/reference/pickedql/index.md +18 -0
  91. package/dist/docs/{pickedql → reference/pickedql}/schema.md +13 -6
  92. package/dist/docs/{pickedql → reference/pickedql}/virtual-functions.md +7 -0
  93. package/dist/docs/reference/sdk/actions.md +30 -0
  94. package/dist/docs/{sdk → reference/sdk}/conditions.md +8 -1
  95. package/dist/docs/reference/sdk/content-security-policy.md +21 -0
  96. package/dist/docs/reference/sdk/experiences.md +51 -0
  97. package/dist/docs/{sdk → reference/sdk}/features.md +30 -117
  98. package/dist/docs/{sdk → reference/sdk}/fields.md +10 -88
  99. package/dist/docs/reference/sdk/index.md +68 -0
  100. package/dist/docs/{sdk → reference/sdk}/plugins/create-experience.md +10 -22
  101. package/dist/docs/reference/sdk/plugins/dynamic-experiences.md +26 -0
  102. package/dist/docs/reference/sdk/plugins/index.md +29 -0
  103. package/dist/docs/{sdk → reference/sdk}/plugins/window-object.md +6 -0
  104. package/dist/docs/reference/sdk/predicates.md +43 -0
  105. package/dist/docs/reference/sdk/ssr/index.md +33 -0
  106. package/dist/docs/{sdk → reference/sdk}/ssr/rendering-and-hydration.md +4 -63
  107. package/dist/docs/{sdk → reference/sdk}/ssr/serialize.md +6 -33
  108. package/dist/docs/{sdk → reference/sdk}/ssr/slots-and-placements.md +7 -1
  109. package/dist/docs/reference/sdk/steps.md +87 -0
  110. package/dist/docs/reference/tools/chrome-extension.md +16 -0
  111. package/dist/docs/{image-optimisation-service.md → reference/tools/image-optimisation-service.md} +8 -0
  112. package/dist/docs/{mcp.md → reference/tools/mcp.md} +5 -45
  113. package/dist/docs/{vite-plugin.md → reference/tools/vite-plugin.md} +8 -38
  114. package/dist/docs/{api/index.md → tutorials/first-api-call.md} +27 -15
  115. package/dist/docs/tutorials/first-experience-in-the-dashboard.mdx +143 -0
  116. package/dist/docs/tutorials/first-experience.mdx +255 -0
  117. package/dist/docs/tutorials/first-server-rendered-page.mdx +186 -0
  118. package/dist/{dom-BwmTHeT7.js → dom-BqcToNL0.js} +1 -3
  119. package/dist/{dom-CDrHc_j9.cjs → dom-DlLH3FxV.cjs} +1 -1
  120. package/dist/esm/form/index.js +2 -4
  121. package/dist/esm/index.js +306 -298
  122. package/dist/esm/plugins/dom-observer/index.js +1 -1
  123. package/dist/esm/plugins/dynamic-experiences/index.js +2 -2
  124. package/dist/esm/preview/index.js +1 -1
  125. package/dist/esm/server/index.js +12 -10
  126. package/dist/{experience-instance-DOJShRk5.js → experience-instance-DGk11d8a.js} +3 -3
  127. package/dist/experience-instance-Dej3P1sE.cjs +1 -0
  128. package/dist/plugin-CNna0UjB.cjs +1 -0
  129. package/dist/{plugin-ChPkTj__.js → plugin-DUOJpHaq.js} +2 -2
  130. package/dist/{preview-channel-DW9J8t4B.js → preview-channel-CSr96XAo.js} +1 -1
  131. package/dist/{protocol-DSqOlW2r.js → protocol-C5KkkiZc.js} +1 -1
  132. package/dist/types/client.d.ts +7 -6
  133. package/dist/types/entities/action/action.d.ts +5 -4
  134. package/dist/types/entities/action/action.d.ts.map +1 -1
  135. package/dist/types/entities/component/component.d.ts +6 -5
  136. package/dist/types/entities/component/component.d.ts.map +1 -1
  137. package/dist/types/entities/condition/condition.d.ts +5 -5
  138. package/dist/types/entities/content/content.d.ts +4 -3
  139. package/dist/types/entities/experience/experience.d.ts +11 -10
  140. package/dist/types/entities/experience/experience.d.ts.map +1 -1
  141. package/dist/types/entities/experience-instance/experience-instance.d.ts +10 -9
  142. package/dist/types/entities/feature/feature.d.ts +19 -2
  143. package/dist/types/entities/feature/feature.d.ts.map +1 -1
  144. package/dist/types/entities/field/field.d.ts +7 -6
  145. package/dist/types/entities/framework/framework.d.ts +7 -6
  146. package/dist/types/entities/framework/framework.d.ts.map +1 -1
  147. package/dist/types/entities/history/history.d.ts +6 -6
  148. package/dist/types/entities/plugin/plugin.d.ts +3 -2
  149. package/dist/types/entities/plugin/plugin.d.ts.map +1 -1
  150. package/dist/types/entities/predicate/predicate.d.ts +4 -3
  151. package/dist/types/entities/predicate/predicate.d.ts.map +1 -1
  152. package/dist/types/entities/response/response-validation.d.ts +3 -2
  153. package/dist/types/entities/response/response.d.ts +12 -11
  154. package/dist/types/entities/session/session.d.ts +2 -1
  155. package/dist/types/entities/step/step.d.ts +6 -5
  156. package/dist/types/exports.d.ts +2 -1
  157. package/dist/types/exports.d.ts.map +1 -1
  158. package/dist/types/form/build-responses.d.ts +2 -1
  159. package/dist/types/form/create-field-evaluator.d.ts +4 -3
  160. package/dist/types/form/create-field-validation.d.ts +5 -4
  161. package/dist/types/form/create-form.d.ts +7 -6
  162. package/dist/types/form/create-submit-pipeline.d.ts +7 -6
  163. package/dist/types/form/get-step-fields.d.ts +3 -2
  164. package/dist/types/lifecycle/condition-selection.d.ts +14 -4
  165. package/dist/types/lifecycle/lifecycle.d.ts +4 -3
  166. package/dist/types/lifecycle/rules-logic.d.ts +4 -3
  167. package/dist/types/lifecycle/state-snapshot.d.ts +4 -3
  168. package/dist/types/picked.d.ts +64 -62
  169. package/dist/types/picked.d.ts.map +1 -1
  170. package/dist/types/ping.d.ts +1 -1
  171. package/dist/types/ping.d.ts.map +1 -1
  172. package/dist/types/plugins/create-experience/create-experience.d.ts +9 -8
  173. package/dist/types/plugins/create-experience/create-experience.d.ts.map +1 -1
  174. package/dist/types/plugins/create-experience/plugin.d.ts +3 -2
  175. package/dist/types/plugins/create-experience/plugin.d.ts.map +1 -1
  176. package/dist/types/plugins/create-experience/serialization.d.ts.map +1 -1
  177. package/dist/types/plugins/dom-observer/plugin.d.ts +1 -1
  178. package/dist/types/plugins/dynamic-experiences/plugin.d.ts +3 -3
  179. package/dist/types/plugins/dynamic-experiences/types.d.ts +8 -5
  180. package/dist/types/plugins/experience-browser-storage/plugin.d.ts +1 -1
  181. package/dist/types/plugins/experience-browser-storage/plugin.d.ts.map +1 -1
  182. package/dist/types/plugins/history-browser-storage/plugin.d.ts +1 -1
  183. package/dist/types/plugins/history-browser-storage/plugin.d.ts.map +1 -1
  184. package/dist/types/plugins/responses-browser-storage/plugin.d.ts +1 -1
  185. package/dist/types/plugins/responses-browser-storage/plugin.d.ts.map +1 -1
  186. package/dist/types/plugins/responses-indexeddb/plugin.d.ts +1 -1
  187. package/dist/types/plugins/single-page-app/plugin.d.ts +1 -1
  188. package/dist/types/plugins/single-page-app/plugin.d.ts.map +1 -1
  189. package/dist/types/plugins/web-components/plugin.d.ts +2 -1
  190. package/dist/types/plugins/window-object/plugin.d.ts +2 -2
  191. package/dist/types/preview-channel.d.ts +5 -1
  192. package/dist/types/preview-receiver/index.d.ts +18 -1
  193. package/dist/types/preview-receiver/protocol.d.ts +10 -1
  194. package/dist/types/server/index.d.ts +3 -3
  195. package/dist/types/server/serialize.d.ts +2 -2
  196. package/dist/types/utils/dom.d.ts +2 -1
  197. package/dist/types/utils/events.d.ts +6 -6
  198. package/dist/types/utils/events.d.ts.map +1 -1
  199. package/dist/types/utils/global-obj.d.ts +1 -1
  200. package/dist/types/utils/global-obj.d.ts.map +1 -1
  201. package/dist/types/utils/id.d.ts.map +1 -1
  202. package/dist/types/utils/logger.d.ts +2 -1
  203. package/dist/types/utils/logger.d.ts.map +1 -1
  204. package/dist/types/utils/node-tree/get-next-node-from-action.d.ts +2 -1
  205. package/dist/types/utils/node-tree/get-next-node-from-condition.d.ts +2 -1
  206. package/dist/types/utils/node-tree/get-next-node.d.ts +1 -1
  207. package/dist/types/utils/node-tree/get-next-node.d.ts.map +1 -1
  208. package/dist/types/utils/node-tree/get-origin-node.d.ts +1 -1
  209. package/dist/types/utils/node-tree/get-origin-node.d.ts.map +1 -1
  210. package/dist/types/utils/node-tree/min-max-steps-to-leaf.d.ts +1 -1
  211. package/dist/types/utils/node-tree/min-max-steps-to-leaf.d.ts.map +1 -1
  212. package/dist/types/utils/node-tree/min-max-steps-to-origin.d.ts +1 -1
  213. package/dist/types/utils/node-tree/min-max-steps-to-origin.d.ts.map +1 -1
  214. package/dist/types/utils/node-tree/next-reachable-step-nodes.d.ts +1 -1
  215. package/dist/types/utils/node-tree/next-reachable-step-nodes.d.ts.map +1 -1
  216. package/dist/types/utils/nodes.d.ts +1 -1
  217. package/dist/types/utils/picked-config.d.ts +2 -1
  218. package/dist/types/utils/rules-logic.d.ts +6 -2
  219. package/dist/types/utils/storage.d.ts +1 -1
  220. package/dist/types/utils/storage.d.ts.map +1 -1
  221. package/package.json +22 -23
  222. package/dist/api-CPy9G49C.js +0 -40
  223. package/dist/api-Ce6xYI--.cjs +0 -1
  224. package/dist/docs/actions.mdx +0 -98
  225. package/dist/docs/api/authentication.md +0 -403
  226. package/dist/docs/chrome-extension.md +0 -68
  227. package/dist/docs/conditions.mdx +0 -72
  228. package/dist/docs/content/asset-library.mdx +0 -124
  229. package/dist/docs/content/pages.mdx +0 -82
  230. package/dist/docs/content/sections.mdx +0 -44
  231. package/dist/docs/delivery-api/index.md +0 -53
  232. package/dist/docs/guides/build-a-personalized-page.mdx +0 -161
  233. package/dist/docs/pickedql/index.md +0 -54
  234. package/dist/docs/projects.mdx +0 -44
  235. package/dist/docs/reports.mdx +0 -20
  236. package/dist/docs/sdk/actions.md +0 -82
  237. package/dist/docs/sdk/content-security-policy.md +0 -33
  238. package/dist/docs/sdk/experiences.md +0 -64
  239. package/dist/docs/sdk/feature-allocation.md +0 -161
  240. package/dist/docs/sdk/index.md +0 -98
  241. package/dist/docs/sdk/plugins/dynamic-experiences.md +0 -84
  242. package/dist/docs/sdk/plugins/index.md +0 -9
  243. package/dist/docs/sdk/predicates.md +0 -128
  244. package/dist/docs/sdk/ssr/index.md +0 -79
  245. package/dist/docs/sdk/steps.md +0 -479
  246. package/dist/docs/steps.mdx +0 -53
  247. package/dist/docs/workspaces.mdx +0 -133
  248. package/dist/experience-instance-DurC3pE-.cjs +0 -1
  249. package/dist/plugin-DHn11gn6.cjs +0 -1
@@ -0,0 +1,143 @@
1
+ ---
2
+ type: tutorial
3
+ layout: docs
4
+ ---
5
+
6
+ import { Screenshot } from '../../../components/Screenshot'
7
+
8
+ # Build your first experience
9
+
10
+ In this tutorial we build a survey and show it to your visitors. We do all of it in the
11
+ Picked dashboard.
12
+
13
+ At the end you have one experience, one step, one field, and a preview of the survey on
14
+ your own site.
15
+
16
+ ## You will need
17
+
18
+ **A Picked account, in an organization.** An organization holds your projects and the
19
+ people who work on them. If you have an invitation, accept it and sign in. If nobody made
20
+ an organization yet, make one from the dashboard home page.
21
+
22
+ **A project.** A project is one site or one application. See
23
+ [How to create a project](/how-to/create-a-project). Keep the project home page open,
24
+ because it shows the SDK snippet that the next item needs.
25
+
26
+ **The URL of your site**, such as `https://www.example.com`. Step 5 opens it to show you
27
+ the survey. It can be a test site.
28
+
29
+ ## What a developer must do first
30
+
31
+ The SDK must be on your site before step 1. This happens one time, and after it you need
32
+ no developer again. Send them these four tasks:
33
+
34
+ 1. Add the SDK to the site. The snippet and the project ID are on the project home page.
35
+ See [How to install the SDK](/how-to/install-the-sdk).
36
+ 2. Make a component that renders a step form.
37
+ 3. [Register that component](/how-to/register-a-component) under the name `ColorSurvey`.
38
+ Step 3 enters the same name in the dashboard, and the two names must match.
39
+ 4. Tell you which site the SDK runs on, so you can open a preview against it.
40
+
41
+ [Add Picked to your application](/tutorials/first-experience) walks a developer through
42
+ all of it.
43
+
44
+ ## 1. Make a field
45
+
46
+ A field collects one answer from your visitor.
47
+
48
+ 1. Open your project.
49
+ 2. Click **Fields** in the sidebar.
50
+ 3. Click **New field**.
51
+ 4. Enter the name `Color`. The dashboard fills in the label and the key for you.
52
+ 5. Change the label to `Which color do you like most?`. Your visitors read the label, and
53
+ they never see the name or the key.
54
+ 6. Leave the key as `color`. You cannot change it later.
55
+ 7. Choose the type **Text**.
56
+ 8. Click **Create field**.
57
+
58
+ <Screenshot
59
+ route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields/new"
60
+ alt="The new field form, with a name, a label, and a key entered"
61
+ fill={{ 'input[name="name"]': 'Color', 'input[name="label"]': 'Which color do you like most?' }}
62
+ />
63
+
64
+ <Screenshot
65
+ route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields"
66
+ alt="The fields list for a workspace on the Picked dashboard"
67
+ />
68
+
69
+ Your field appears in the fields list.
70
+
71
+ ## 2. Make the experience
72
+
73
+ 1. Click **Flows** in the sidebar. The experiences list opens.
74
+ 2. Click **New experience**.
75
+ 3. Enter the name `Color survey`.
76
+ 4. Leave **Type** on the **Flow** option. A flow is the interactive kind, and it is what
77
+ this tutorial builds. See [About pages and flows](/explanation/pages-and-flows) for the
78
+ other kind.
79
+ 5. Open **Advanced**.
80
+ 6. Enter the component name `ColorSurvey`. This is the name your developer registered.
81
+ 7. Click **Create flow**.
82
+
83
+ The flow builder opens with an empty canvas. One gray circle sits on the left. That
84
+ circle is the origin, and every flow starts there.
85
+
86
+ ## 3. Make a step
87
+
88
+ A step is one screen that your visitor sees. It holds your field. You make one from the
89
+ library, on the left of the flow builder.
90
+
91
+ 1. Find the **Steps** section in the library.
92
+ 2. Click the **+** next to it.
93
+ 3. Enter the name `Question`. The key fills in as `question`.
94
+ 4. Click **Create step**.
95
+
96
+ The flow builder opens again, and your step is in the library.
97
+
98
+ ## 4. Build the flow
99
+
100
+ 1. Find your `Question` step under **Steps** in the library.
101
+ 2. Drag it onto the canvas.
102
+ 3. Drag from the output handle of the origin to the input handle of your step. An arrow
103
+ joins them.
104
+ 4. Drag your `Color` field from the library onto the step node.
105
+ 5. Click **Save** in the toolbar.
106
+
107
+ <Screenshot
108
+ route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences/{experienceId}"
109
+ alt="The flow builder with the library, canvas, and inspector panels"
110
+ />
111
+
112
+ The subtitle of the step node now reads one field. Your flow is one step long, and it
113
+ starts at the origin.
114
+
115
+ ## 5. Preview it
116
+
117
+ A preview opens your own site with this workspace applied. Your visitors see no change.
118
+
119
+ 1. Click **Preview** in the workspace toolbar.
120
+ 2. Enter the URL of your site.
121
+ 3. Click **Open preview**.
122
+
123
+ Your site opens in a new tab, and your survey is on it. Enter a color and continue.
124
+
125
+ ## 6. Publish it
126
+
127
+ 1. Click **Publish** in the workspace toolbar.
128
+ 2. Read the change preview. It lists what your visitors get.
129
+ 3. Click **Publish** to confirm.
130
+
131
+ Your survey is live.
132
+
133
+ ## What you built
134
+
135
+ You have an experience that your visitors see. The dashboard holds the flow, the step, and
136
+ the field, so you change any of them and publish again without a deployment.
137
+
138
+ ## Where to go next
139
+
140
+ - [How to build a flow](/how-to/build-a-flow) — branches, actions, and conditions.
141
+ - [How to run an A/B test](/how-to/run-an-ab-test) — show a change to some visitors.
142
+ - [About how Picked works](/explanation/how-picked-works) — what happens when you
143
+ publish.
@@ -0,0 +1,255 @@
1
+ ---
2
+ type: tutorial
3
+ layout: docs
4
+ ---
5
+
6
+ import { Screenshot } from '../../../components/Screenshot'
7
+
8
+ # Add Picked to your application
9
+
10
+ In this tutorial we make a color survey and put it on a page. We build the flow in the
11
+ Picked dashboard, connect the SDK to it, and see the survey in a browser.
12
+
13
+ At the end you have one experience, one step, one field, and a page that shows them.
14
+
15
+ ## Before you start
16
+
17
+ - A Picked account, and an organization in it.
18
+ - Node 20 or later.
19
+ - A web application that runs React or Svelte. A new Vite application is enough.
20
+
21
+ ## 1. Make a project
22
+
23
+ A project is one site or one application.
24
+
25
+ 1. Sign in to the dashboard.
26
+ 2. Open your organization.
27
+ 3. Click **New Project**.
28
+ 4. Enter the name `Tutorial`.
29
+ 5. Click **Create**.
30
+
31
+ The project home page opens. It shows a project ID near the top. Copy that ID. Every step
32
+ after this one needs it.
33
+
34
+ ## 2. Make a field
35
+
36
+ A field collects one answer from your visitor.
37
+
38
+ 1. Click **Fields** in the sidebar.
39
+ 2. Click **New field**.
40
+ 3. Enter the name `Color`. The dashboard fills in the label and the key for you.
41
+ 4. Change the label to `Which color do you like most?`.
42
+ 5. Leave the key as `color`.
43
+ 6. Choose the type **Text**.
44
+ 7. Click **Create field**.
45
+
46
+ <Screenshot
47
+ route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields"
48
+ alt="The fields list for a workspace on the Picked dashboard"
49
+ />
50
+
51
+ The field now appears in the fields list.
52
+
53
+ ## 3. Make the experience
54
+
55
+ 1. Click **Flows** in the sidebar. The experiences list opens.
56
+ 2. Click **New experience**.
57
+ 3. Enter the name `Color survey`.
58
+ 4. Leave **Type** on the **Flow** option.
59
+ 5. Open **Advanced**.
60
+ 6. Enter the component name `ColorSurvey`.
61
+ 7. Click **Create flow**.
62
+
63
+ The flow builder opens with an empty canvas. One gray circle is on the left. That circle
64
+ is the origin, and every flow starts there.
65
+
66
+ ## 4. Make a step
67
+
68
+ A step is one screen that your visitor sees. It holds your field. You make one from the
69
+ library, on the left of the flow builder.
70
+
71
+ 1. Find the **Steps** section in the library.
72
+ 2. Click the **+** next to it.
73
+ 3. Enter the name `Question`. The key fills in as `question`.
74
+ 4. Click **Create step**.
75
+
76
+ The flow builder opens again, and your step is in the library.
77
+
78
+ ## 5. Build the flow
79
+
80
+ 1. Find your `Question` step in the library on the left.
81
+ 2. Drag it onto the canvas.
82
+ 3. Drag from the output handle of the origin to the input handle of your step. An arrow
83
+ joins them.
84
+ 4. Drag your `Color` field from the library onto the step node.
85
+ 5. Click **Save** in the toolbar.
86
+
87
+ The subtitle of the step node now reads one field. Your flow is one step long, and it
88
+ starts at the origin.
89
+
90
+ ## 6. Publish the workspace
91
+
92
+ Your visitors see nothing until you publish.
93
+
94
+ 1. Click **Publish** in the workspace toolbar.
95
+ 2. Read the change preview.
96
+ 3. Click **Publish** to confirm.
97
+
98
+ ## 7. Connect the SDK
99
+
100
+ Install the client and the adapter for your framework.
101
+
102
+ :::code-group
103
+
104
+ ```bash [React]
105
+ npm install @picked/client @picked/react effector effector-react
106
+ ```
107
+
108
+ ```bash [Svelte]
109
+ npm install @picked/client @picked/svelte effector
110
+ ```
111
+
112
+ :::
113
+
114
+ Now write the component that renders the step. Put it in `ColorSurvey.tsx`, or in
115
+ `ColorSurvey.svelte`. It reads the fields of the active step and
116
+ puts each one in a form.
117
+
118
+ :::code-group
119
+
120
+ ```tsx [React]
121
+ import { useStep } from '@picked/react/hooks'
122
+ import { useUnit } from 'effector-react'
123
+
124
+ export function ColorSurvey() {
125
+ const { fields, form } = useStep()
126
+ const currentFields = useUnit(fields)
127
+
128
+ return (
129
+ <form {...form.props}>
130
+ {currentFields.map((field) => (
131
+ <div key={field.id}>
132
+ <label htmlFor={field.id}>{field.label}</label>
133
+ <input
134
+ id={field.id}
135
+ name={field.id}
136
+ value={field.value ?? ''}
137
+ onChange={field.onChange}
138
+ onBlur={field.onBlur}
139
+ />
140
+ </div>
141
+ ))}
142
+ <button type="submit">Continue</button>
143
+ </form>
144
+ )
145
+ }
146
+ ```
147
+
148
+ ```svelte [Svelte]
149
+ <script lang="ts">
150
+ import { getStep } from '@picked/svelte/hooks'
151
+
152
+ const { fields, form } = getStep()
153
+ </script>
154
+
155
+ <form {...form.props}>
156
+ {#each $fields as field}
157
+ <div>
158
+ <label for={field.id}>{field.label}</label>
159
+ <input
160
+ id={field.id}
161
+ name={field.id}
162
+ value={field.value ?? ''}
163
+ onchange={field.onChange}
164
+ onblur={field.onBlur}
165
+ />
166
+ </div>
167
+ {/each}
168
+ <button type="submit">Continue</button>
169
+ </form>
170
+ ```
171
+
172
+ :::
173
+
174
+ Then start the client from `picked.ts`. Put your project ID in `projectId`. The key in `components` must
175
+ match the component name that you entered in step 4.
176
+
177
+ :::code-group
178
+
179
+ ```tsx [React]
180
+ import { createClient } from '@picked/client'
181
+ import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
182
+ import { adaptReactComponent } from '@picked/react'
183
+ import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
184
+ import { ColorSurvey } from './ColorSurvey'
185
+
186
+ export const picked = createClient({
187
+ projectId: 'your-project-id',
188
+ components: {
189
+ ColorSurvey: adaptReactComponent(ColorSurvey),
190
+ },
191
+ plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
192
+ })
193
+
194
+ picked.start()
195
+ ```
196
+
197
+ ```ts [Svelte]
198
+ import { createClient } from '@picked/client'
199
+ import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
200
+ import { adaptSvelteComponent } from '@picked/svelte'
201
+ import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
202
+ import ColorSurvey from './ColorSurvey.svelte'
203
+
204
+ export const picked = createClient({
205
+ projectId: 'your-project-id',
206
+ components: {
207
+ ColorSurvey: adaptSvelteComponent(ColorSurvey),
208
+ },
209
+ plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
210
+ })
211
+
212
+ picked.start()
213
+ ```
214
+
215
+ :::
216
+
217
+ `dynamicExperiencesPlugin` reads the published configuration of your project. It registers your
218
+ experience, your step, and your field. You declare none of them in code.
219
+
220
+ ## 8. See it
221
+
222
+ Start your application and open it in a browser.
223
+
224
+ Your survey appears. It shows the label `Which color do you like most?` and one text
225
+ input. Both come from the dashboard, and neither is in your code.
226
+
227
+ ## 9. Change it without a deployment
228
+
229
+ This step shows you what the dashboard controls.
230
+
231
+ 1. Go back to the dashboard.
232
+ 2. Open your `Color` field.
233
+ 3. Change the label to `Which color do you like least?`.
234
+ 4. Click **Save**.
235
+ 5. Publish the workspace again.
236
+ 6. Open the page in your browser again.
237
+
238
+ The question changes. You edited no code and you deployed nothing.
239
+
240
+ ## What you built
241
+
242
+ You have an experience that you control from the dashboard and render in your own
243
+ application. The dashboard holds the flow, the step, and the field. Your code holds only
244
+ the component and the client.
245
+
246
+ To change the label, the field type, or the order of the steps, edit the workspace and
247
+ publish again. You deploy no code.
248
+
249
+ ## Where to go next
250
+
251
+ - [Your first server-rendered page](/tutorials/first-server-rendered-page) — a page that
252
+ a search engine can read.
253
+ - [How to build a flow](/how-to/build-a-flow) — branches, actions, and conditions.
254
+ - [About how Picked works](/explanation/how-picked-works) — what happens between publish
255
+ and render.
@@ -0,0 +1,186 @@
1
+ ---
2
+ type: tutorial
3
+ layout: docs
4
+ ---
5
+
6
+ import { Screenshot } from '../../../components/Screenshot'
7
+
8
+ # Your first server-rendered page
9
+
10
+ In this tutorial we make a landing page in the Picked CMS and render it on your server.
11
+ A search engine reads the content in the first response, and the browser takes over after
12
+ that.
13
+
14
+ At the end you have one page layout, one content entry, and a server that returns your
15
+ content in its HTML.
16
+
17
+ ## Before you start
18
+
19
+ - A Picked project. [Add Picked to your application](/tutorials/first-experience)
20
+ makes one.
21
+ - A server that renders React or Svelte and can add a script tag to its HTML.
22
+ - Node 20 or later.
23
+
24
+ ## 1. Model the page layout
25
+
26
+ A page layout sets which fields your page holds.
27
+
28
+ 1. Open your workspace.
29
+ 2. Click **Pages** in the sidebar, then **Page Layouts**.
30
+ 3. Click **New model**.
31
+ 4. Set **Category** to **Page layout**.
32
+ 5. Enter the name `Page hero` and the key `page-hero`. The key is stable, and your SDK
33
+ code and your API calls both use it.
34
+ 6. Add a **Single-line text** field with the key `title`.
35
+ 7. Add a **Markdown** field with the key `body`.
36
+ 8. Click **Create model**.
37
+
38
+ <Screenshot
39
+ route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/models"
40
+ alt="A page layout in the schema builder on the Picked dashboard"
41
+ />
42
+
43
+ Your layout now holds two fields. It holds no content yet.
44
+
45
+ ## 2. Make the page and fill it
46
+
47
+ 1. Click **Pages** in the sidebar.
48
+ 2. Click **New Experience**.
49
+ 3. Choose the **Page** type.
50
+ 4. Choose your `page-hero` layout.
51
+ 5. Open the **Properties** tab.
52
+ 6. Enter a `title` and a `body`.
53
+ 7. Click **Save**. Picked makes a content entry and links it to the page.
54
+ 8. Correct every field error.
55
+
56
+ ## 3. Publish the workspace
57
+
58
+ 1. Click **Publish** in the workspace toolbar.
59
+ 2. Click **Publish** to confirm.
60
+
61
+ Your content is now live. Read it back with `curl`, and put your own project ID in the
62
+ path:
63
+
64
+ ```bash
65
+ curl https://api.picked.app/api/v1/projects/proj_123
66
+ ```
67
+
68
+ The answer holds your steps. Each one carries a `layoutContentId`, which points at the
69
+ content entry behind it.
70
+
71
+ ## 4. Make the snapshot on your server
72
+
73
+ `serialize()` finds which experiences match the URL and reads their content. It gives you
74
+ a snapshot as plain JSON.
75
+
76
+ Make one client for each request, in `server.ts`:
77
+
78
+ ```ts
79
+ import { createClient } from '@picked/client'
80
+ import { serialize } from '@picked/client/server'
81
+
82
+ const client = createClient(options)
83
+
84
+ const snapshot = await serialize(client, {
85
+ projectConfig,
86
+ attributes: { location: { pathname: url.pathname } },
87
+ })
88
+ ```
89
+
90
+ Write the snapshot into your HTML answer:
91
+
92
+ ```ts
93
+ const html = `
94
+ <div id="root">${appHtml}</div>
95
+ <script>window.__PICKED__ = ${JSON.stringify(snapshot)}</script>
96
+ `
97
+ ```
98
+
99
+ ## 5. Render the slot
100
+
101
+ `<ExperienceSlot name="page" />` renders every experience that points at that slot. Give
102
+ the provider your snapshot, so the first paint in the browser matches the HTML from your
103
+ server.
104
+
105
+ Register the component under the same name that the page uses. Here it is `CMSPage`.
106
+
107
+ :::code-group
108
+
109
+ ```tsx [React]
110
+ import type { CreateClientOptions } from '@picked/client'
111
+ import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
112
+ import { adaptReactComponent, ExperienceSlot, PickedProvider } from '@picked/react'
113
+ import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
114
+ import { useStepContent } from '@picked/react/hooks'
115
+
116
+ function CMSPage() {
117
+ const content = useStepContent()
118
+ const title = typeof content?.title === 'string' ? content.title : ''
119
+ return <h1>{title}</h1>
120
+ }
121
+
122
+ const options = {
123
+ projectId: 'proj_123',
124
+ components: { CMSPage: adaptReactComponent(CMSPage) },
125
+ plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
126
+ } satisfies CreateClientOptions
127
+
128
+ export function Page({ snapshot }) {
129
+ return (
130
+ <PickedProvider options={options} snapshot={snapshot}>
131
+ <ExperienceSlot name="page" />
132
+ </PickedProvider>
133
+ )
134
+ }
135
+ ```
136
+
137
+ ```svelte [Svelte]
138
+ <script lang="ts">
139
+ import type { CreateClientOptions } from '@picked/client'
140
+ import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
141
+ import { adaptSvelteComponent, ExperienceSlot, setPickedContext } from '@picked/svelte'
142
+ import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
143
+ import CMSPage from './CMSPage.svelte'
144
+
145
+ const { snapshot } = $props()
146
+
147
+ const options = {
148
+ projectId: 'proj_123',
149
+ components: { CMSPage: adaptSvelteComponent(CMSPage) },
150
+ plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
151
+ } satisfies CreateClientOptions
152
+
153
+ setPickedContext({ options, snapshot })
154
+ </script>
155
+
156
+ <ExperienceSlot name="page" />
157
+ ```
158
+
159
+ :::
160
+
161
+ Point your page experience at the slot. Set its target selector to `.picked-slot-page`,
162
+ and publish again.
163
+
164
+ ## 6. Check that a crawler can read it
165
+
166
+ 1. Read the answer from your server with `curl`, or with the view-source command of your
167
+ browser.
168
+ 2. Find your `title` in the HTML.
169
+
170
+ Your title is in the first response, not in a script that the browser must run. A crawler
171
+ and a social preview both read it.
172
+
173
+ ## What you built
174
+
175
+ You have a page whose content lives in the Picked CMS and whose HTML comes from your
176
+ server. An editor changes the copy in the dashboard and publishes. Your server serves the
177
+ new content on the next request, and you deploy nothing.
178
+
179
+ ## Where to go next
180
+
181
+ - [About server-side rendering](/explanation/why-server-side-rendering) — why the
182
+ snapshot exists, and what it carries.
183
+ - [Server snapshot](/reference/sdk/ssr/serialize) — every `serialize()` parameter.
184
+ - [Page and step layouts](/reference/dashboard/content/layouts) — every field type.
185
+ - [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — how
186
+ a draft stays out of the search index.
@@ -72,9 +72,7 @@ function _(e, t, n, r) {
72
72
  case "prepend":
73
73
  e.prepend(a);
74
74
  break;
75
- case "append":
76
- e.append(a);
77
- break;
75
+ case "append": e.append(a);
78
76
  }
79
77
  i = a;
80
78
  }
@@ -1 +1 @@
1
- const e=require("./supports-DBzjGaWD.cjs");function t(t){return!e.f()||!e.i()?[]:Array.from(window.document.querySelectorAll(t)).filter(e=>e instanceof HTMLElement)}var n=`open`;function r(t){if(!e.u())throw Error(`Shadow DOM is not supported in this environment`);return t.attachShadow({mode:n})}function i(){return new Promise((t,n)=>{if(!e.i()){n();return}document.readyState===`loading`?document.addEventListener(`readystatechange`,()=>t(),{once:!0}):t()})}function a(e,t){let n=new MutationObserver(r=>{document.contains(e)||(n.disconnect(),t())});n.observe(document.body,{childList:!0,subtree:!0})}var o=`picked-root`,s=`picked-target`,c=`picked-root`;function l(e,n){return[...e,{selector:`${c}[experience-id="${n}"]`,placement:`replace`}].flatMap(e=>{let r=t(e.selector).filter(e=>!f(e,n)&&!p(e,n));return{...e,elements:r}})}function u(e,t,n){return e.flatMap(e=>e.elements.map(r=>h(r,e.placement,t,n)))}function d(e,t){e.classList.add(s),e.classList.add(`${s}-${t}`)}function f(e,t){return t?e.classList.contains(`${s}-${t}`):e.classList.contains(`${s}`)}function p(e,t){return t?e.classList.contains(`${o}-${t}`):e.classList.contains(o)}function m(e,t){let n=document.createElement(`div`);return n.style.display=`block`,n.classList.add(o),n.classList.add(`${o}-${e}`),n.classList.add(`${o}-${t}`),n}function h(e,t,n,r){let i,a=m(n,r);if(e instanceof Document)i=e.body.appendChild(a);else{switch(t){case`replace`:e.replaceWith(a);break;case`before`:e.before(a);break;case`after`:e.after(a);break;case`prepend`:e.prepend(a);break;case`append`:e.append(a);break}i=a}return i}Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return u}});
1
+ const e=require("./supports-DBzjGaWD.cjs");function t(t){return!e.f()||!e.i()?[]:Array.from(window.document.querySelectorAll(t)).filter(e=>e instanceof HTMLElement)}var n=`open`;function r(t){if(!e.u())throw Error(`Shadow DOM is not supported in this environment`);return t.attachShadow({mode:n})}function i(){return new Promise((t,n)=>{if(!e.i()){n();return}document.readyState===`loading`?document.addEventListener(`readystatechange`,()=>t(),{once:!0}):t()})}function a(e,t){let n=new MutationObserver(r=>{document.contains(e)||(n.disconnect(),t())});n.observe(document.body,{childList:!0,subtree:!0})}var o=`picked-root`,s=`picked-target`,c=`picked-root`;function l(e,n){return[...e,{selector:`${c}[experience-id="${n}"]`,placement:`replace`}].flatMap(e=>{let r=t(e.selector).filter(e=>!f(e,n)&&!p(e,n));return{...e,elements:r}})}function u(e,t,n){return e.flatMap(e=>e.elements.map(r=>h(r,e.placement,t,n)))}function d(e,t){e.classList.add(s),e.classList.add(`${s}-${t}`)}function f(e,t){return t?e.classList.contains(`${s}-${t}`):e.classList.contains(`${s}`)}function p(e,t){return t?e.classList.contains(`${o}-${t}`):e.classList.contains(o)}function m(e,t){let n=document.createElement(`div`);return n.style.display=`block`,n.classList.add(o),n.classList.add(`${o}-${e}`),n.classList.add(`${o}-${t}`),n}function h(e,t,n,r){let i,a=m(n,r);if(e instanceof Document)i=e.body.appendChild(a);else{switch(t){case`replace`:e.replaceWith(a);break;case`before`:e.before(a);break;case`after`:e.after(a);break;case`prepend`:e.prepend(a);break;case`append`:e.append(a)}i=a}return i}Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return u}});
@@ -9,7 +9,7 @@ function c(e, t, n) {
9
9
  return;
10
10
  }
11
11
  if (Array.isArray(r) && Array.isArray(n) && n.length > 0) {
12
- typeof r[0] == "string" ? e[t] = [...r, ...n].map(String) : typeof r[0] == "number" ? e[t] = [...r, ...n].map(Number) : typeof r[0] == "boolean" ? e[t] = [...r, ...n].map((e) => !!e) : e[t] = n;
12
+ e[t] = typeof r[0] == "string" ? [...r, ...n].map(String) : typeof r[0] == "number" ? [...r, ...n].map(Number) : typeof r[0] == "boolean" ? [...r, ...n].map((e) => !!e) : n;
13
13
  return;
14
14
  }
15
15
  e[t] = n;
@@ -31,9 +31,7 @@ function l(e, t) {
31
31
  case "number":
32
32
  c(r, e.key, e.multiple ? [Number(t)] : Number(t));
33
33
  break;
34
- case "boolean":
35
- c(r, e.key, e.multiple ? [t === "true"] : t === "true");
36
- break;
34
+ case "boolean": c(r, e.key, e.multiple ? [t === "true"] : t === "true");
37
35
  }
38
36
  });
39
37
  }), r;