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

package/dist/docs/reference/sdk/ssr/rendering-and-hydration.md

@@ -1,103 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Rendering and Hydration
-
-Seed a Picked client from the server snapshot, render your slots, and hydrate. This
-page covers React and Svelte.
-
-## React: `PickedProvider`
-
-`PickedProvider` gives a client to each component below it. Its props are a union of
-two modes:
-
-| Props | Mode | Description |
-| --- | --- | --- |
-| `{ options, snapshot? }` | Create | The provider calls `createClient(options)` and hydrates the client from the snapshot. |
-| `{ client, snapshot? }` | Adopt | The provider uses a client that is there already, such as a global one for the whole application. It can also seed that client from the snapshot. |
-
-The provider seeds the client at once, so the server and the first paint on the
-client give the same markup. In the browser the provider calls `client.start()` from
-an effect. `start()` is idempotent, so it changes nothing on a client that already
-started.
-
-```tsx
-import { PickedProvider, ExperienceSlot } from '@picked/react'
-
-<PickedProvider options={options} snapshot={snapshot}>
-  <ExperienceSlot name="page" />
-</PickedProvider>
-```
-
-## Svelte: `setPickedContext`
-
-`setPickedContext` does the same work in the Svelte style. Call it one time at the
-top of the `<script>` block of a component. It takes the same two modes,
-`{ options, snapshot? }` or `{ client, snapshot? }`, and it returns the client.
-
-```svelte
-<script lang="ts">
-  import { ExperienceSlot, setPickedContext } from '@picked/svelte'
-
-  setPickedContext({ options, snapshot })
-</script>
-
-<ExperienceSlot name="page" />
-```
-
-## Render the page component
-
-The SDK does not connect content to a component. You own the component that a Page
-renders. Register it under the name that the Page uses. The Page Layout in the dashboard
-points at that same name. The component reads the resolved entry data
-through a content hook: `useStepContent()` in React, and `getStepContent()` in
-Svelte.
-
-:::code-group
-
-```tsx [React]
-import { useStepContent } from '@picked/react/hooks'
-
-export function CMSPage() {
-  const content = useStepContent()
-  if (!content) {
-    return <p>Loading page content…</p>
-  }
-
-  const title = typeof content.title === 'string' ? content.title : ''
-  return (
-    <article>
-      <h1>{title}</h1>
-    </article>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStepContent } from '@picked/svelte/hooks'
-
-  const content = getStepContent()
-</script>
-
-{#if $content}
-  <article>
-    <h1>{typeof $content.title === 'string' ? $content.title : ''}</h1>
-  </article>
-{:else}
-  <p>Loading page content…</p>
-{/if}
-```
-
-:::
-
-`useStepContent()` returns the `data` object of the entry directly. It returns `null`
-while no content is registered. `getStepContent()` returns a store, and you read it
-with `$content`.
-
-## Related
-
-- [How to server-render a page](/how-to/server-render-a-page) — the full example.
-- [Slots and placements](/reference/sdk/ssr/slots-and-placements)

package/dist/docs/reference/sdk/ssr/serialize.md

@@ -1,80 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Server Snapshot
-
-`serialize()` finds which experiences match a URL and reads their content on the
-server. It returns a snapshot as plain JSON, and you pass that snapshot to the
-client.
-
-## The `serialize(client, params)` function
-
-```ts
-import { createClient } from 'picked'
-import { serialize } from '@picked/client/server'
-
-const client = createClient(options)
-
-const snapshot = await serialize(client, {
-  projectConfig,
-  attributes: { location: { pathname: '/promo' } },
-})
-```
-
-`serialize()` does this. It registers the project configuration on the client at once. It
-evaluates the condition of each experience against `attributes.location`. It reads
-the content for each experience whose steps point at layout content. It removes the
-duplicate content blobs, which it finds by their IDs. It then returns a `PickedSnapshot`.
-
-The content that it reads holds the entries of the steps. It also holds the entries that
-a [reference field](/reference/dashboard/content/models#reference-fields) reaches.
-
-Give `serialize()` one client for each request. It does not support two calls at the
-same time on one client.
-
-```ts
-serialize(client: Picked, params: SerializeParams): Promise<PickedSnapshot>
-```
-
-## Parameters
-
-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| `projectConfig` | `ProjectConfig` | required | The published configuration, or the preview configuration, to register and choose against. |
-| `attributes.location` | `Partial<SerializeLocation>` | none | The URL fields that go into the selection context, such as `pathname`. |
-| `getContent` | `SerializeGetContent` | runtime API | Your own function to read content, in place of the runtime API. |
-| `previewToken` | `string` | none | The SDK sends this with the content request, so that preview content resolves during a preview render. |
-| `timeoutMs` | `number` | `10000` | The limit for each content request. After the limit, the SDK skips that blob and continues. |
-
-`SerializeLocation` carries the URL fields `href`, `pathname`, `search`, `hostname`,
-`origin`, `protocol`, `port`, `host`, and `hash`. Pass only the fields that your
-conditions read.
-
-## The snapshot
-
-```ts
-interface PickedSnapshot {
-  versionId: string | null
-  projectConfig: ProjectConfig
-  content: ContentBlob[]
-  conditionResults: Record<string, boolean>
-}
-```
-
-| Field | Description |
-| --- | --- |
-| `versionId` | The project version that the snapshot was chosen against. It is `null` when the version is not known, for example in a preview. |
-| `projectConfig` | The options that the server chose with. They travel to the client, so that the client renders against exactly the same options. |
-| `content` | The content blobs for the chosen experiences, with the duplicates removed. It holds the entries of the steps, and every entry that a reference field reaches. The server render and the first paint in the browser therefore resolve the same pointers. |
-| `conditionResults` | The condition results that the server kept, under a key made from the rule hash. The client then reuses the choice of the server. |
-
-The snapshot is plain JSON. Write it into your HTML response with `JSON.stringify`
-and read it back on the client.
-
-## Related
-
-- [How to server-render a page](/how-to/server-render-a-page)
-- [How to render an unpublished preview](/how-to/render-an-unpublished-preview)
-- [Content](/reference/sdk/content) — how to read a content record in a component.

package/dist/docs/reference/sdk/ssr/slots-and-placements.md

@@ -1,113 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Slots and Placements
-
-A slot is a named mount point. `<ExperienceSlot name="page" />` renders every
-experience that points at that slot and whose condition matches.
-
-## What a slot is
-
-The `name` of a slot points at the `.picked-slot-<name>` selector. So
-`<ExperienceSlot name="page" />` renders every experience with the target selector
-`.picked-slot-page`, when the condition of that experience is active.
-
-The slot reads the active state of each experience from the seeded snapshot. It
-therefore renders at once, both in server-side rendering and at the first paint of
-the hydration.
-
-```tsx
-<ExperienceSlot name="page" />
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `name` | `string` | — | The name of the slot. It points at the `.picked-slot-<name>` selector. |
-| `open` | `'rule' \| 'rendered'` | `'rule'` | What an experience does when its `initializeOpen` is empty. `'rule'` keeps it closed. `'rendered'` opens it. A boolean or a rule in `initializeOpen` has the same result with both values. |
-| `wrap` | `boolean` | `false` | Puts the output of each experience in a wrapper element. See [The wrapper](#the-wrapper). |
-
-The slot reads `open` when it mounts an experience.
-
-## Point an experience at a slot
-
-Set the target selector of the experience to `.picked-slot-<name>`. An experience
-that points at `.picked-slot-page` renders into `<ExperienceSlot name="page" />`. The
-name of the slot and the end of the selector must match.
-
-## Placement order
-
-When more than one experience points at the same slot, they render in this placement
-order:
-
-```
-replace -> before -> prepend -> append -> after
-```
-
-`replace` wins. An active experience with the `replace` placement renders alone, and
-it replaces every other match in the slot. In every other case each active experience
-renders, in placement order.
-
-## More than one experience in one slot
-
-The slot collects each experience that points at its selector. It drops each one
-whose condition is not active. It then sorts the rest into placement order. When a `replace`
-experience is among the active ones, only that experience renders. With no active
-`replace`, the slot renders every active experience in the order `before`, `prepend`,
-`append`, `after`.
-
-One Page can therefore take a whole slot with `replace`, while another slot holds
-several experiences that use the other placements. A condition decides which
-experiences are active. See [Conditions](/reference/dashboard/conditions).
-
-## Lifecycle events
-
-The slot sends these events on the event bus of the client for each experience that it
-renders. It sends them only in the browser, and only after the client is ready. The server
-render sends no events.
-
-| Bus event | When it fires | Analytics event |
-| --- | --- | --- |
-| `experience_initialize` | The slot mounts the experience. | `experience_load` |
-| `experience_open` | The experience opens. `open` and `initializeOpen` decide this. | `app_open` |
-| `step_enter` | The flow of an open experience arrives at a step. | `step_enter` |
-| `experience_unmount` | The slot stops rendering the experience. | None |
-
-When the slot stops rendering an experience, the open state of that experience does not
-change. The slot therefore sends no `experience_close`, and the analytics plugin sends no
-`app_close`. After that, the experience sends no events, and its flow stops.
-
-Each time that the slot mounts an experience, the experience starts closed, and `open` and
-`initializeOpen` decide again if it opens. This is also true when the slot mounts the same
-experience again, for example after a React `<Activity>` shows it again.
-
-The flow of an experience continues from its history. When the history of an experience
-already ends at a step, the experience opens at that step and the slot sends no
-`step_enter` for it.
-
-Each analytics event has the page URL at the time that the event fires.
-
-## The wrapper
-
-With `wrap`, the slot puts the output of each experience in one element:
-
-```html
-<div data-picked-experience-id="<experience id>" style="display: contents">
-  <!-- the experience -->
-</div>
-```
-
-The element has no box of its own, so the layout does not change. The element is in the
-document tree, so the selectors `>`, `:first-child`, and `:nth-child()` see it. The
-`data-picked-experience-id` attribute holds the ID of the experience. It is the same on the
-server and in the browser.
-
-Without `wrap`, the slot adds no element.
-
-## Related
-
-- [About server-side rendering](/explanation/why-server-side-rendering) — why placements
-  have an order.

package/dist/docs/reference/sdk/steps.md

@@ -1,86 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Steps
-
-Render your steps with `<StepRouter>` and `<Step>` from `@picked/react` or
-`@picked/svelte`. Reach the active step through `useStep()` or `getStep()`.
-
-## Reach the step context
-
-Inside a `Step` component, or inside any component that a `Step` renders, call
-`getStep()` or `useStep()` to reach the reactive context of the step:
-
-:::code-group
-
-```tsx [React]
-import { useStep, useStoreGlobal } from '@picked/react/hooks'
-
-function ContactForm() {
-  const { step, fields } = useStep()
-  const currentStep = useStoreGlobal(step)
-  const currentFields = useStoreGlobal(fields)
-
-  return (
-    <>
-      <h1>{currentStep.label}</h1>
-
-      {currentFields.map((field) => (
-        <div key={field.id}>
-          <label>{field.label}</label>
-          <input
-            name={field.id}
-            value={field.value ?? ''}
-            onChange={field.onChange}
-            onBlur={field.onBlur}
-          />
-          {field.error && field.touched && <p className="error">{field.error.userMessage}</p>}
-        </div>
-      ))}
-    </>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStep } from '@picked/svelte/hooks'
-
-  const { step, fields } = getStep()
-</script>
-
-<h1>{$step.label}</h1>
-
-{#each $fields as field}
-  <label>{field.label}</label>
-  <input
-    name={field.id}
-    value={field.value ?? ''}
-    onchange={field.onChange}
-    onblur={field.onBlur}
-  />
-  {#if field.error && field.touched}
-    <p class="error">{field.error.userMessage}</p>
-  {/if}
-{/each}
-```
-
-:::
-
-`getStep()` in Svelte, and `useStep()` in React, return a `StepContext` with these
-properties:
-
-| Property   | Type                                          | Description                                                                    |
-| ---------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
-| `step`     | `Store<ExperienceStep>`                       | A reactive store that holds the `id` and the `label` of the step                |
-| `fields`   | `Store<FormField[]>`                          | A reactive store of the fields, with their current values, errors, and handlers |
-| `isActive` | `Store<boolean>` (Svelte) / `boolean` (React) | Whether the router holds this step as the active one                            |
-| `form`     | Object                                        | The handlers for a form submission. See [Forms](#forms).                        |
-
-## Related
-
-- [How to render a step form](/how-to/render-a-step-form)
-- [How to run code on a form submission](/how-to/run-code-on-a-form-submission)
-- [About how Picked works](/explanation/how-picked-works) — why a flow is a graph.

package/dist/docs/reference/sdk/type-generation.md

@@ -1,265 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Type Generation
-
-Picked can generate TypeScript types from your workspace schema so field values, feature keys, content models, and step layouts are typed in your app.
-
-## Quick start
-
-### 1. Add `picked.config.ts`
-
-Create a `picked.config.ts` in your project root:
-
-```typescript
-import { defineConfig } from 'picked/config'
-
-export default defineConfig({
-  projectId: 'your-project-id',
-  typesOutput: './src/picked-env.d.ts',
-})
-```
-
-| Option | Description |
-| --- | --- |
-| `projectId` | **Required.** Your Picked project id. |
-| `typesOutput` | Path for generated types (defaults to `./src/picked-env.d.ts`). |
-| `source` | Schema surface to type against: `'published'` (default) or `'preview'`. |
-| `previewToken` | Workspace preview token. Required when `source` is `'preview'`, and read only then. |
-
-The `source` value matches the `x-picked-source` field on the [workspace schema](/reference/delivery-api/workspace-schema) document — it controls whether tooling fetches the published or preview workspace shape.
-
-A preview token reads one workspace, and it does not expire. Leave both `source` and
-`previewToken` out of the committed file, and pick a workspace instead:
-
-```bash
-picked login
-picked workspace use
-```
-
-That writes the choice, and that workspace's token, to `.picked/settings.json`, which is
-per-developer and which Git ignores. Each developer points at their own workspace, and the
-committed file holds no token.
-
-You can also set the values here. Every developer then reads the same workspace:
-
-```typescript
-export default defineConfig({
-  projectId: 'your-project-id',
-  source: 'preview',
-  previewToken: 'the-workspace-preview-token',
-})
-```
-
-Three places can give the token. Tooling reads the first of them that has one: the
-`PICKED_PREVIEW_TOKEN` environment variable, then the workspace that
-[`picked workspace use`](/reference/tools/cli) chose, then this `previewToken` option.
-
-### 2. Enable the Vite plugin (recommended)
-
-If you use Vite, add `@picked/vite-plugin-picked`. Type generation runs automatically on `dev` and `build` when `generateTypes` is enabled (the default):
-
-```typescript
-import { picked } from '@picked/vite-plugin-picked'
-
-export default defineConfig({
-  plugins: [picked()],
-})
-```
-
-The project id comes from `picked.config.ts`. A failure stops the
-run. See [the plugin reference](/reference/tools/vite-plugin) for `generateTypes` and every
-other option.
-
-### 3. Or use the CLI
-
-Install [`picked`](/reference/tools/cli) and run:
-
-```bash
-picked generate types
-```
-
-## Keep the types current
-
-Commit `picked-env.d.ts`. A workspace changes after you commit it, so the file goes stale,
-and stale types describe fields your workspace no longer has.
-
-Run this check in CI, next to your other checks:
-
-```bash
-picked generate types --check
-```
-
-`--check` writes no file. It reads the live workspace schema and compares it with the
-committed file. A match gives status `0`. A difference gives status `1` and names the file:
-
-```
-Types are out of date: /home/runner/work/your-app/src/picked-env.d.ts
-```
-
-To clear it, run `picked generate types` and commit the result. The check reads no cached
-schema, so an API it cannot reach fails the check.
-
-:::note
-`--check` reads the workspace that the resolved configuration names. A CI run that has no
-`.picked/settings.json` reads the workspace your committed `picked.config.ts` names.
-:::
-
-## Workspace selection
-
-Tooling reads `projectId` and `source` from your committed `picked.config.ts`. The Picked [CLI](/reference/tools/cli) points that tooling at a different project or a draft workspace, and leaves the file as it is. It writes the selection to `.picked/settings.json`, which is per-developer and which Git ignores. That selection supersedes the committed default.
-
-See [How to switch workspaces](/how-to/switch-workspaces) for the full set of steps.
-
-## Generated output
-
-The generated `picked-env.d.ts` file looks like:
-
-```typescript
-// GENERATED by `@picked/typegen` — do not edit by hand.
-// Reference: `https://docs.picked.app/reference/sdk/type-generation`
-
-export type WelcomePage = { /* ... */ }
-export type FieldValues = { /* ... */ }
-export type FeatureKey =
-  | 'default'
-  | 'hero'
-  | 'winter-sale'
-
-declare module '@picked/client' {
-  interface PickedSchemaRegistry {
-    contentModels: {
-      'welcome-page': WelcomePage
-    }
-    stepContentModels: {
-      'intro': 'welcome-page'
-    }
-    featureValues: {
-      'hero':
-        | false
-        | 'hero-a'
-        | 'hero-b'
-    }
-    fieldValues: FieldValues
-    featureKeys: FeatureKey
-  }
-}
-```
-
-Commit this file to the version control system, or regenerate it in CI after you publish a workspace change.
-
-### Feature flag values
-
-A Text feature flag declares the values that it can serve, so `useFeatureResult` narrows
-the bucket to those values:
-
-```typescript
-const result = useFeatureResult('hero')
-```
-
-The `bucket` property then has the type `false | 'hero-a' | 'hero-b'`.
-
-`featureValues` holds the Text feature flags alone. A Boolean feature flag, and a feature
-flag that your application defines, both keep the general `boolean | string` type. The
-`FeatureValueFor<'hero'>` type gives the same union on its own.
-
-### Assets
-
-An `asset` field is a union. An asset that the API finds has a `url`, and an asset that
-it does not find has no `url`.
-[Field values](/reference/delivery-api/workspace-schema#field-values) gives the two shapes.
-The `in` operator narrows the union:
-
-```tsx
-const image = page.hero_image
-
-return 'url' in image ? <img src={image.url} width={image.width ?? undefined} alt="" /> : null
-```
-
-### Content blocks
-
-Each block type has a `contentBlockKey` property whose type is the key of the block. A
-`switch` on that property gives the `data` type of each block:
-
-```tsx
-for (const section of page.sections ?? []) {
-  switch (section.contentBlockKey) {
-    case 'faq':
-      renderFaq(section.data.items)
-      break
-    case 'hero':
-      renderHero(section.data.headline)
-      break
-  }
-}
-```
-
-### The model of a record
-
-`isContentOfModel(record, key)` from `@picked/client` returns `true` when the
-`contentModelKey` of the record is `key`. In that branch, `record.data` has the generated
-type of the model. `ContentRecordOf<'landing-page'>` gives the same record type, and
-`ContentModelKeys` holds the keys of the models in the workspace.
-
-In this example, one component renders the layouts of two models:
-
-```tsx
-import { isContentOfModel } from '@picked/client'
-import { useStepLayoutContent } from '@picked/react/hooks'
-
-export function Page() {
-  const record = useStepLayoutContent()
-
-  if (record && isContentOfModel(record, 'landing-page')) {
-    return <LandingPage content={record.data} />
-  }
-
-  if (record && isContentOfModel(record, 'standard-page')) {
-    return <StandardPage content={record.data} />
-  }
-
-  return null
-}
-```
-
-The check reads `contentModelKey` only. It does not validate `data` against the model.
-
-## Keys the application defines
-
-An application can define a feature, an action, a field, a step, or an experience of its
-own. It does this through `createClient` options or through a `register` method. The
-workspace has no record of such a key, so the generated types have none either.
-
-A hook still accepts one. Each key type holds the keys of the workspace and any other
-string. Your editor shows the workspace keys, and no local key is an error:
-
-```typescript
-useFeature('winter-sale')             // from the workspace, and suggested
-useFeature('summer-sales-experiment') // from createClient, and accepted
-```
-
-Each key type has a `Known` form that holds the workspace keys alone —
-`KnownFeatureKeys`, `KnownActionKeys`, `KnownFieldKeys`, `KnownStepKeys`, and
-`KnownExperienceKeys`. Use one where you want the workspace set and nothing else.
-
-## Actions that start a workflow
-
-`WorkflowActionKeys` holds the keys of the actions that start a workflow in the workspace. For one
-of these keys, the types of `useAction` and `getAction` give `run`, `status`, `response` and
-`error`. For every other key, the types give the action as a function. Without generated types,
-and with a schema that has no such actions, `WorkflowActionKeys` is `never`. See
-[Actions](/reference/sdk/actions).
-
-## Cache
-
-Type generation writes its artefacts under `.picked/`: the schema JSON and a manifest. The first run adds this directory to `.gitignore` for you.
-
-## Related
-
-- [CLI](/reference/tools/cli) — commands, authentication, and environment variables.
-- [How to switch workspaces](/how-to/switch-workspaces) — read a draft workspace on your machine.
-- [Vite plugin](/reference/tools/vite-plugin) — the build-time prefetch and the dev launcher.
-- [Workspace schema](/reference/delivery-api/workspace-schema) — the schema endpoint.
-- [Delivery API](/reference/delivery-api) — the published surface and the preview surface.

package/dist/docs/reference/tools/chrome-extension.md

@@ -1,16 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Chrome Extension
-
-The extension for the Picked Developer Tools adds a Picked panel to Chrome DevTools.
-Use the panel to check and debug your Picked integration on any page that runs the
-SDK.
-
-![Picked Developer Tools](/chrome-extension-screenshot.jpg)
-
-## Related
-
-- [How to debug with the Chrome extension](/how-to/debug-with-the-chrome-extension)