picked 0.0.101-next.2 → 0.0.101

package/docs/reference/sdk/svelte.md

@@ -0,0 +1,74 @@
+---
+type: reference
+layout: docs
+---
+
+# Svelte
+
+`@picked/svelte` lets the Picked client render Svelte components, and gives functions and
+components to read the client from Svelte.
+
+| Peer dependency | Version |
+| --- | --- |
+| `svelte` | `^5.55.7` |
+| `@picked/client` | The version of your Picked SDK |
+| `effector` | `^23.4.4` |
+
+## Entry points
+
+| Import | Exports |
+| --- | --- |
+| `@picked/svelte` | `adaptSvelteComponent`, `isValidAdaptedComponent`, `setPickedContext`, `ExperienceSlot`, `HtmlRender`, `LazyImage` |
+| `@picked/svelte/plugins/framework` | `svelteFrameworkPlugin` |
+| `@picked/svelte/plugins/devtools` | `svelteDevtoolsPlugin` |
+| `@picked/svelte/hooks` | `getPicked`, `getExperience`, `getStep`, `getStepContent`, `getStepLayoutContent`, `setStepContext`, `getFeature`, `getFeatureResult`, `getFeatureEnabled`, `getPredicate`, `getPredicateResult`, `getAction`, `getActionResult`, `getContent`, `getReference`, `getReferences`, `createQuery`, `createSessionStorageStore`, `createLocalStorageStore`, `useUnit` |
+| `@picked/svelte/router` | `StepRouter`, `Step` |
+| `@picked/svelte/form` | `getForm` |
+| `@picked/svelte/server` | `renderer`, which renders a Svelte component to HTML on the server |
+
+## Framework plugin
+
+`svelteFrameworkPlugin` registers Svelte as a framework of the client. The client then
+renders each Svelte component in a shadow root.
+
+```ts
+import { createClient } from 'picked'
+import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [svelteFrameworkPlugin({ components: {} })],
+})
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `components` | `{ experience?: { component, style? } }` | required | `experience` renders each experience that has no component of its own. |
+| `stylesheets` | `string[]` | none | The URLs of stylesheets to add to each shadow root. |
+| `css` | `string[]` | none | CSS text to add to each shadow root. |
+
+## Devtools plugin
+
+`svelteDevtoolsPlugin` connects the client to the Picked Chrome extension.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | When `true`, the devtools open on page load. When `false`, the Chrome extension opens them. |
+| `customTools` | `CustomTool[]` | `[]` | Your own tools, which show in the Custom Tools tab. |
+
+When a preview token is there, the devtools launcher shows, even if `enabled` is `false`.
+See [How to debug with the Chrome extension](/how-to/debug-with-the-chrome-extension).
+
+## Components
+
+`adaptSvelteComponent(component)` makes a Svelte component that the client can render. It
+takes a component, a dynamic import, or a lazy loader. See
+[How to register a component](/how-to/register-a-component).
+
+## Related
+
+- [How to install the SDK](/how-to/install-the-sdk)
+- [Steps](/reference/sdk/steps)
+- [Features](/reference/sdk/features)
+- [Content](/reference/sdk/content)
+- [Rendering and hydration](/reference/sdk/ssr/rendering-and-hydration)

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

@@ -0,0 +1,265 @@
+---
+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/docs/reference/tools/admin-api-client.md

@@ -0,0 +1,89 @@
+---
+type: reference
+layout: docs
+---
+
+# Management API client
+
+`@picked/admin-api-client` is a typed GraphQL client for the Management API. It gets the
+type of each result and its variables from the API schema.
+
+```ts
+import { createAdminApiClient, graphql } from '@picked/admin-api-client'
+
+const MeQuery = graphql(`
+  query Me {
+    user {
+      id
+      email
+    }
+  }
+`)
+
+const client = createAdminApiClient({
+  apiUrl: 'https://api.picked.app',
+  apiKey: process.env.PICKED_API_KEY,
+})
+
+const data = await client.request(MeQuery, {})
+```
+
+## Client options
+
+`createAdminApiClient(options)` returns a client. The client sends each request to
+`<apiUrl>/api/graphql`.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiUrl` | `string` | required | The origin of the API, for example `https://api.picked.app`. |
+| `token` | `string \| (() => string \| Promise<string>)` | none | A bearer token. A function gives a new token for each request. |
+| `apiKey` | `string` | none | An API key. The client sends it in the `X-API-Key` header. |
+
+See [Authentication](/reference/management-api/authentication) for the tokens and keys
+that the API accepts.
+
+## Requests
+
+```ts
+client.request(document, variables, options?): Promise<Result>
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `document` | `TadaDocumentNode` | A document that `graphql` makes. |
+| `variables` | `object` | The variables of the document. Use `{}` for a document without variables. |
+| `options.timeoutMs` | `number` | The time limit of the request in milliseconds. The default is `30000`. |
+
+The client does not check the shape of the response at runtime.
+
+## Errors
+
+| Case | Error |
+| --- | --- |
+| The API returns GraphQL errors | `AdminApiResponseError`. Its `codes` holds the `extensions.code` of each error. |
+| A network failure, a timeout, or an HTTP error without GraphQL errors | `Error` |
+
+See [Errors](/reference/management-api/error-handling) for each error code.
+
+## Workspace documents
+
+The package also gives the documents that move a workspace from one project to a
+different project:
+
+| Document | Operation |
+| --- | --- |
+| `WorkspaceExportDocument` | Reads the full contents of a workspace. |
+| `ProjectLiveVersionDocument` | Reads the live version of a project. |
+| `WorkspaceImportDocument` | Makes a workspace from those contents. |
+| `AssetUploadInitDocument` | Gives a URL that receives the file of an asset. |
+| `AssetCommitDocument` | Records an asset after its file is at that URL. |
+| `AssetDeleteDocument` | Deletes an asset. |
+| `WorkspacePublishDocument` | Publishes a workspace. |
+
+The `picked workspace export` and `picked workspace import` commands use these documents.
+See [CLI](/reference/tools/cli).
+
+## Related
+
+- [Authentication](/reference/management-api/authentication)
+- [About the two APIs](/explanation/the-two-apis)

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

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