@picked/client 0.0.101-next.2 → 0.0.101-next.3

package/dist/docs/tutorials/first-experience.mdx

@@ -1,254 +0,0 @@
----
-type: tutorial
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Add Picked to your application
-
-In this tutorial we make a color survey and put it on a page. We build the flow in the
-Picked dashboard, connect the SDK to it, and see the survey in a browser.
-
-At the end you have one experience, one step, one field, and a page that shows them.
-
-## Before you start
-
-- A Picked account, and an organization in it.
-- Node 20 or later.
-- A web application that runs React or Svelte. A new Vite application is enough.
-
-## 1. Make a project
-
-A project is one site or one application.
-
-1. Sign in to the dashboard.
-2. Open your organization.
-3. Click **New Project**.
-4. Enter the name `Tutorial`.
-5. Click **Create**.
-
-The project home page opens. It shows a project ID near the top. Copy that ID. Every step
-after this one needs it.
-
-## 2. Make a field
-
-A field collects one answer from your visitor.
-
-1. Click **Fields** in the sidebar.
-2. Click **New field**.
-3. Enter the name `Color`. The dashboard fills in the label and the key for you.
-4. Change the label to `Which color do you like most?`.
-5. Leave the key as `color`.
-6. Choose the type **Text**.
-7. Click **Create field**.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields"
-  alt="The fields list for a workspace on the Picked dashboard"
-/>
-
-The field now appears in the fields list.
-
-## 3. Make the experience
-
-1. Click **Flows** in the sidebar. The experiences list opens.
-2. Click **New experience**.
-3. Enter the name `Color survey`.
-4. Leave **Type** on the **Flow** option.
-5. Open **Advanced**.
-6. Enter the component name `ColorSurvey`.
-7. Click **Create flow**.
-
-The flow builder opens with an empty canvas. One gray circle is on the left. That circle
-is the origin, and every flow starts there.
-
-## 4. Make a step
-
-A step is one screen that your visitor sees. It holds your field. You make one from the
-library, on the left of the flow builder.
-
-1. Find the **Steps** section in the library.
-2. Click the **+** next to it.
-3. Enter the name `Question`. The key fills in as `question`.
-4. Click **Create step**.
-
-The flow builder opens again, and your step is in the library.
-
-## 5. Build the flow
-
-1. Find your `Question` step in the library on the left.
-2. Drag it onto the canvas.
-3. Drag from the output handle of the origin to the input handle of your step. An arrow
-   joins them.
-4. Drag your `Color` field from the library onto the step node.
-5. Click **Save** in the toolbar.
-
-The subtitle of the step node now reads one field. Your flow is one step long, and it
-starts at the origin.
-
-## 6. Publish the workspace
-
-Your visitors see nothing until you publish.
-
-1. Click **Publish** in the workspace toolbar.
-2. Read the change preview.
-3. Click **Publish** to confirm.
-
-## 7. Connect the SDK
-
-Install the client and the adapter for your framework.
-
-:::code-group
-
-```bash [React]
-npm install picked @picked/react
-```
-
-```bash [Svelte]
-npm install picked @picked/svelte
-```
-
-:::
-
-Now write the component that renders the step. Put it in `ColorSurvey.tsx`, or in
-`ColorSurvey.svelte`. It reads the fields of the active step and
-puts each one in a form.
-
-:::code-group
-
-```tsx [React]
-import { useStep, useStoreGlobal } from '@picked/react/hooks'
-
-export function ColorSurvey() {
-  const { fields, form } = useStep()
-  const currentFields = useStoreGlobal(fields)
-
-  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}
-          />
-        </div>
-      ))}
-      <button type="submit">Continue</button>
-    </form>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStep } from '@picked/svelte/hooks'
-
-  const { fields, form } = getStep()
-</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}
-      />
-    </div>
-  {/each}
-  <button type="submit">Continue</button>
-</form>
-```
-
-:::
-
-Then start the client from `picked.ts`. Put your project ID in `projectId`. The key in `components` must
-match the component name that you entered in step 4.
-
-:::code-group
-
-```tsx [React]
-import { createClient } from 'picked'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { adaptReactComponent } from '@picked/react'
-import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
-import { ColorSurvey } from './ColorSurvey'
-
-export const picked = createClient({
-  projectId: 'your-project-id',
-  components: {
-    ColorSurvey: adaptReactComponent(ColorSurvey),
-  },
-  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-})
-
-picked.start()
-```
-
-```ts [Svelte]
-import { createClient } from 'picked'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { adaptSvelteComponent } from '@picked/svelte'
-import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
-import ColorSurvey from './ColorSurvey.svelte'
-
-export const picked = createClient({
-  projectId: 'your-project-id',
-  components: {
-    ColorSurvey: adaptSvelteComponent(ColorSurvey),
-  },
-  plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-})
-
-picked.start()
-```
-
-:::
-
-`dynamicExperiencesPlugin` reads the published configuration of your project. It registers your
-experience, your step, and your field. You declare none of them in code.
-
-## 8. See it
-
-Start your application and open it in a browser.
-
-Your survey appears. It shows the label `Which color do you like most?` and one text
-input. Both come from the dashboard, and neither is in your code.
-
-## 9. Change it without a deployment
-
-This step shows you what the dashboard controls.
-
-1. Go back to the dashboard.
-2. Open your `Color` field.
-3. Change the label to `Which color do you like least?`.
-4. Click **Save**.
-5. Publish the workspace again.
-6. Open the page in your browser again.
-
-The question changes. You edited no code and you deployed nothing.
-
-## What you built
-
-You have an experience that you control from the dashboard and render in your own
-application. The dashboard holds the flow, the step, and the field. Your code holds only
-the component and the client.
-
-To change the label, the field type, or the order of the steps, edit the workspace and
-publish again. You deploy no code.
-
-## Where to go next
-
-- [Your first server-rendered page](/tutorials/first-server-rendered-page) — a page that
-  a search engine can read.
-- [How to build a flow](/how-to/build-a-flow) — branches, actions, and conditions.
-- [About how Picked works](/explanation/how-picked-works) — what happens between publish
-  and render.

package/dist/docs/tutorials/first-server-rendered-page.mdx

@@ -1,186 +0,0 @@
----
-type: tutorial
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Your first server-rendered page
-
-In this tutorial we make a landing page in the Picked CMS and render it on your server.
-A search engine reads the content in the first response, and the browser takes over after
-that.
-
-At the end you have one page layout, one content entry, and a server that returns your
-content in its HTML.
-
-## Before you start
-
-- A Picked project. [Add Picked to your application](/tutorials/first-experience)
-  makes one.
-- A server that renders React or Svelte and can add a script tag to its HTML.
-- Node 20 or later.
-
-## 1. Model the page layout
-
-A page layout sets which fields your page holds.
-
-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 the name `Page hero` and the key `page-hero`. The key is stable, and your SDK
-   code and your API calls both use it.
-6. Add a **Single-line text** field with the key `title`.
-7. Add a **Markdown** field with the key `body`.
-8. Click **Create model**.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/models"
-  alt="A page layout in the schema builder on the Picked dashboard"
-/>
-
-Your layout now holds two fields. It holds no content yet.
-
-## 2. Make the page and fill it
-
-1. Click **Pages** in the sidebar.
-2. Click **New Experience**.
-3. Choose the **Page** type.
-4. Choose your `page-hero` layout.
-5. Open the **Properties** tab.
-6. Enter a `title` and a `body`.
-7. Click **Save**. Picked makes a content entry and links it to the page.
-8. Correct every field error.
-
-## 3. Publish the workspace
-
-1. Click **Publish** in the workspace toolbar.
-2. Click **Publish** to confirm.
-
-Your content is now live. Read it back with `curl`, and put your own project ID in the
-path:
-
-```bash
-curl https://api.picked.app/api/v1/projects/proj_123
-```
-
-The answer holds your steps. Each one carries a `layoutContentId`, which points at the
-content entry behind it.
-
-## 4. Make the snapshot on your server
-
-`serialize()` finds which experiences match the URL and reads their content. It gives you
-a snapshot as plain JSON.
-
-Make one client for each request, in `server.ts`:
-
-```ts
-import { createClient } from 'picked'
-import { serialize } from '@picked/client/server'
-
-const client = createClient(options)
-
-const snapshot = await serialize(client, {
-  projectConfig,
-  attributes: { location: { pathname: url.pathname } },
-})
-```
-
-Write the snapshot into your HTML answer:
-
-```ts
-const html = `
-  <div id="root">${appHtml}</div>
-  <script>window.__PICKED__ = ${JSON.stringify(snapshot)}</script>
-`
-```
-
-## 5. Render the slot
-
-`<ExperienceSlot name="page" />` renders every experience that points at that slot. Give
-the provider your snapshot, so the first paint in the browser matches the HTML from your
-server.
-
-Register the component under the same name that the page uses. Here it is `CMSPage`.
-
-:::code-group
-
-```tsx [React]
-import type { CreateClientOptions } from 'picked'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { adaptReactComponent, ExperienceSlot, PickedProvider } from '@picked/react'
-import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
-import { useStepContent } from '@picked/react/hooks'
-
-function CMSPage() {
-  const content = useStepContent()
-  const title = typeof content?.title === 'string' ? content.title : ''
-  return <h1>{title}</h1>
-}
-
-const options = {
-  projectId: 'proj_123',
-  components: { CMSPage: adaptReactComponent(CMSPage) },
-  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-} satisfies CreateClientOptions
-
-export function Page({ snapshot }) {
-  return (
-    <PickedProvider options={options} snapshot={snapshot}>
-      <ExperienceSlot name="page" />
-    </PickedProvider>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import type { CreateClientOptions } from 'picked'
-  import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-  import { adaptSvelteComponent, ExperienceSlot, setPickedContext } from '@picked/svelte'
-  import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
-  import CMSPage from './CMSPage.svelte'
-
-  const { snapshot } = $props()
-
-  const options = {
-    projectId: 'proj_123',
-    components: { CMSPage: adaptSvelteComponent(CMSPage) },
-    plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-  } satisfies CreateClientOptions
-
-  setPickedContext({ options, snapshot })
-</script>
-
-<ExperienceSlot name="page" />
-```
-
-:::
-
-Point your page experience at the slot. Set its target selector to `.picked-slot-page`,
-and publish again.
-
-## 6. Check that a crawler can read it
-
-1. Read the answer from your server with `curl`, or with the view-source command of your
-   browser.
-2. Find your `title` in the HTML.
-
-Your title is in the first response, not in a script that the browser must run. A crawler
-and a social preview both read it.
-
-## What you built
-
-You have a page whose content lives in the Picked CMS and whose HTML comes from your
-server. An editor changes the copy in the dashboard and publishes. Your server serves the
-new content on the next request, and you deploy nothing.
-
-## Where to go next
-
-- [About server-side rendering](/explanation/why-server-side-rendering) — why the
-  snapshot exists, and what it carries.
-- [Server snapshot](/reference/sdk/ssr/serialize) — every `serialize()` parameter.
-- [Models](/reference/dashboard/content/models) — every field type.
-- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — how
-  a draft stays out of the search index.