@picked/client 0.0.1-dev.1788925875333 → 0.0.1-next.1

package/dist/docs/how-to/define-a-page-layout.md

@@ -1,46 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to define a page layout
-
-This guide shows you how to define the shape of a page. A page layout sets which fields a
-page can hold, and it holds no data itself.
-
-## Steps
-
-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 a **Name** and a **Key**. The key is stable, and your SDK code and your API
-   calls both use it.
-6. Add your fields. Choose a type for each one.
-7. Click **Create model**.
-
-The category is fixed when you create the Model. You cannot change it later.
-
-## Make a field repeatable
-
-Turn on **repeatable** on any field. It then renders as a sortable list of values. Use it
-for a gallery, or for a list of features.
-
-## Group related fields
-
-Add a **Group** field to hold a set of fields under one key. Make the group repeatable to
-describe a list of objects, such as a list of feature cards.
-
-## Define content with no layout role
-
-A Model needs no category. Leave **Category** as **None (general content)** for content
-that no Page and no Step renders, such as an author or a product. Reach such a Model
-under **CMS** in the sidebar, and point at its entries with a **Reference** field.
-
-## Related
-
-- [About the content model](/explanation/the-content-model) — why the schema and the data
-  are separate.
-- [Models](/reference/dashboard/content/models) — every field type.
-- [How to reuse a section](/how-to/reuse-a-section)
-- [How to point one entry at another](/how-to/point-one-entry-at-another)

package/dist/docs/how-to/fill-and-publish-a-page.md

@@ -1,66 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to fill and publish a page
-
-This guide shows you how to make a server-rendered Page and put content in it. You need a
-page layout first. See [How to define a page layout](/how-to/define-a-page-layout).
-
-## 1. Create the page
-
-1. Open your project.
-2. Choose a workspace.
-3. Click **Pages** in the sidebar.
-4. Click **New experience**.
-5. Choose the **Page** type.
-6. Choose a page layout.
-7. Click **Create page**.
-
-Picked makes a content entry and links it to the page on the first save.
-
-## 2. Fill in the content
-
-1. Open the **Properties** tab.
-2. Fill in each field. The inspector on the right edits the field that you choose.
-3. Watch the preview panel as the page fills in.
-
-## 3. Correct every error
-
-An invalid field shows an error next to it while you edit. Correct each one before you
-publish. Picked serves valid content only.
-
-## 4. Choose the status
-
-Open the **Settings** tab and set the status.
-
-- Set **Active** to serve the page to everyone.
-- Set **Draft** to keep the page out of the published site. Picked serves a
-  draft page through a preview link, and to nobody else.
-
-Use **Draft** for a page that is ready to review but not ready to be public.
-When you publish the workspace, Picked releases your other changes and leaves
-that page staged.
-
-## 5. Publish
-
-Publish the workspace to apply your changes to the live site. See
-[How to publish a workspace](/how-to/publish-a-workspace).
-
-When you publish the workspace, Picked does not make a draft page public. To
-make that page public, set the status to **Active** and publish the workspace
-again.
-
-## Change the layout later
-
-Use the change-layout control on the **Settings** tab. When you unlink a layout, Picked
-separates the content entry from the page. It deletes no entry, but the page then has no
-content to render.
-
-## Related
-
-- [About pages and flows](/explanation/pages-and-flows) — when to choose a Page.
-- [Your first server-rendered page](/tutorials/first-server-rendered-page) — the whole
-  path, with the SDK.
-- [Pages](/reference/dashboard/content/pages) — the editor reference.

package/dist/docs/how-to/install-the-gtm-template.md

@@ -1,84 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to install the GTM template
-
-This guide shows you how to track an ecommerce event in Google Tag Manager and send it to
-Picked. You need a GTM container and your Picked Tag ID.
-
-## Automatic installation
-
-Install the template from the GTM Community Gallery:
-
-1. In Tag Manager, click **Templates**.
-2. In the **Tag Templates** section, click **Search Gallery**.
-3. Search for `Picked Ecommerce`.
-4. Click the Picked Ecommerce template to read its detail.
-5. Click the **Add to workspace** button.
-6. Read the permissions that it needs.
-7. Click **Add**.
-
-![The Picked Ecommerce template in the GTM Community Gallery](/gtm/picked-ecommerce-gtm.png)
-
-## Manual installation
-
-To import the template file yourself:
-
-1. Download the
-   [template file](https://github.com/picked-app/gtm-template/blob/main/template.tpl)
-   from GitHub with the download icon.
-2. In Google Tag Manager, go to **Templates**.
-3. Click **New**.
-4. Open the three-dot menu.
-5. Click **Import**.
-6. Choose the file that you downloaded.
-7. Click **Save**.
-
-## Setup
-
-### 1. Create a Tag ID variable
-
-Sign in to the [Picked Dashboard](https://dashboard.picked.app) and copy the Tag ID of
-your project. Save it as a constant variable in GTM, for example `Picked Tag ID`.
-
-![How to create a variable in GTM for the Picked Tag ID](/gtm/gtm-variable.png)
-
-### 2. Create an ecommerce data variable
-
-Create a **Data Layer Variable** with the variable name `ecommerce`. It captures what
-GA4 Enhanced Ecommerce writes to the data layer.
-
-![The variable for the data layer of GA4 Enhanced Ecommerce](/gtm/gtm-ecommerce-variable.png)
-
-### 3. Create event triggers
-
-Add a trigger for each ecommerce event that you want to track, for example
-`add_to_cart`, `purchase`, or `view_item`.
-
-![The event triggers that record an ecommerce event](/gtm/gtm-triggers.png)
-
-### 4. Create tags
-
-Create a new tag for each event. Choose the tag template called **Picked Ecommerce**. Assign
-the trigger that matches. Then set the options below.
-
-![The tags that use the Picked Ecommerce template](/gtm/gtm-tags.png)
-
-## Options
-
-| Option | Description |
-| --- | --- |
-| **Tag ID** | The Tag ID of your Picked project. Find it in the [Picked Dashboard](https://dashboard.picked.app). |
-| **Event** | The ecommerce event to track, for example `add_to_cart` or `purchase`. |
-| **Send ecommerce data** | Turn this on to send the data from GA4 Enhanced Ecommerce to Picked. Turn it on for every ecommerce event. |
-| **GA4 Enhanced Ecommerce Data** | The GTM variable that holds the data from GA4 Enhanced Ecommerce. Use the data layer variable from step 2. |
-| **Additional data** | An optional GTM variable, for more metadata with the event. |
-
-![The options on a Picked Ecommerce tag](/gtm/gtm-tag.png)
-
-## Related
-
-- [About how Picked works](/explanation/how-picked-works) — what Picked does with the
-  event.

package/dist/docs/how-to/install-the-sdk.md

@@ -1,93 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to install the SDK
-
-This guide shows you how to add the Picked client to a web application. You need a project
-ID from the dashboard.
-
-## 1. Install the packages
-
-:::code-group
-
-```bash [React]
-npm install picked @picked/react
-```
-
-```bash [Svelte]
-npm install picked @picked/svelte
-```
-
-:::
-
-`picked` gives you the client, the `picked.config` helpers, and the `picked` command. Your
-package manager adds `@picked/client` with it, which carries the runtime and holds the
-generated types.
-
-## 2. Add `picked.config.ts`
-
-Create this file in the root of your project. The `picked` command and the
-[Vite plugin](/reference/tools/vite-plugin) read your project identity from it:
-
-```typescript
-import { defineConfig } from 'picked/config'
-
-export default defineConfig({
-  projectId: 'your-project-id',
-})
-```
-
-[Type generation](/reference/sdk/type-generation) reads this file, and gives your fields,
-features and steps the types the workspace declares.
-
-## 3. Create and start the client
-
-:::code-group
-
-```tsx [React]
-import { createClient } from 'picked'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
-
-export const picked = createClient({
-  projectId: 'your-project-id',
-  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-})
-
-picked.start()
-```
-
-```ts [Svelte]
-import { createClient } from 'picked'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
-
-export const picked = createClient({
-  projectId: 'your-project-id',
-  plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-})
-
-picked.start()
-```
-
-:::
-
-`picked` carries the client's root entry. Each deeper import path, such as
-`@picked/client/plugins/dynamic-experiences` and `@picked/client/server`, keeps its own
-name.
-
-`start()` is idempotent. A second call changes nothing on a client that started already.
-
-## 4. Add the optional plugins
-
-- `windowObjectPlugin()` puts the client on `window.Picked`, which helps when you debug.
-- `singlePageAppPlugin()` starts the client again on a history event.
-
-## Related
-
-- [Add Picked to your application](/tutorials/first-experience) — the whole path.
-- [SDK installation](/reference/sdk) — every client option.
-- [Type generation](/reference/sdk/type-generation) — types from your workspace.
-- [How to register a component](/how-to/register-a-component).

package/dist/docs/how-to/install-the-vite-plugin.md

@@ -1,69 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to install the Vite plugin
-
-This guide shows you how to embed your project configuration at build time, so the SDK makes no
-API request at runtime.
-
-## 1. Install
-
-:::code-group
-
-```bash [npm]
-npm install @picked/vite-plugin-picked picked
-```
-
-```bash [pnpm]
-pnpm add @picked/vite-plugin-picked picked
-```
-
-```bash [yarn]
-yarn add @picked/vite-plugin-picked picked
-```
-
-:::
-
-## 2. Name your project
-
-Create `picked.config.ts` in the root of your project. The plugin reads your project
-identity from this file:
-
-```typescript
-import { defineConfig } from 'picked/config'
-
-export default defineConfig({
-  projectId: 'your-project-id',
-})
-```
-
-## 3. Add the plugin to your Vite config
-
-```typescript
-import { defineConfig } from 'vite'
-import { picked } from '@picked/vite-plugin-picked'
-
-export default defineConfig({
-  plugins: [picked()],
-})
-```
-
-When Vite starts, the plugin reads your project configuration and embeds them in your bundle.
-The SDK then reads the embedded configuration and makes no network request.
-
-The plugin also writes `picked-env.d.ts`, which types your fields, features and steps
-against the workspace. See [Type generation](/reference/sdk/type-generation).
-
-:::note
-When a preview token is there at runtime, the SDK ignores the embedded configuration and reads
-fresh data from the API.
-:::
-
-## Related
-
-- [Vite plugin](/reference/tools/vite-plugin) — every option.
-- [Type generation](/reference/sdk/type-generation) — the `picked.config.ts` options.
-- [About how Picked works](/explanation/how-picked-works) — where build-time configuration sit
-  in the startup order.

package/dist/docs/how-to/invite-and-remove-members.md

@@ -1,34 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to invite and remove members
-
-This guide shows you how to control who reaches your organization.
-
-## Invite a member
-
-1. Open your organization.
-2. Click **Members**.
-3. Click **Invite member**.
-4. Enter an email address.
-5. Choose a role. Give the smallest role that the work needs.
-6. Click **Send invitation**.
-
-The person receives an email with a link to join. A person with no Picked account must
-create one first.
-
-## Remove a member
-
-1. Open your organization.
-2. Click **Members**.
-3. Find the member.
-4. Click **Remove** next to the name.
-5. Confirm.
-
-The member loses access to every project in the organization immediately.
-
-## Related
-
-- [Team management](/reference/dashboard/team-management) — the roles.

package/dist/docs/how-to/point-one-entry-at-another.md

@@ -1,61 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to point one entry at another
-
-This guide shows you how to point one content entry at another, such as a product at its
-category. You need two Models: the one that holds the pointer, and the one that the
-pointer reaches.
-
-## 1. Create the target Model
-
-1. Click **CMS** in the sidebar, then **Models**.
-2. Click **New model**.
-3. Enter a **Name** and a **Key**, such as `category`.
-4. Leave **Category** as **None (general content)**.
-5. Add your fields.
-6. Click **Create model**.
-
-## 2. Add a Reference field
-
-1. Open the Model that holds the pointer.
-2. Drag a **Reference** property onto the schema.
-3. Enter a **Name** and a **Key**, such as `category`.
-4. Set **Target Model** to the Model from step 1.
-5. Click **Save**.
-
-Turn on **repeatable** for a field that points at more than one entry. Leave **Target
-Model** as **Any Model** to accept an entry of any Model in the workspace.
-
-## 3. Choose a target on an entry
-
-1. Open a content entry that uses the Model.
-2. Find your Reference field.
-3. Click **Choose entry**.
-4. Search for the entry.
-5. Choose the entry.
-6. Click **Save**.
-
-Use **Change entry** to point the field somewhere else. Use **Clear** to remove the
-pointer. **Clear** deletes no content.
-
-## Delete a target
-
-Picked does not delete an entry while another entry points at it. Clear the reference on
-each entry that points at the target, then delete the target.
-
-The same rule holds for a Model. Remove the Reference field that holds it as its **Target
-Model** first.
-
-## Read it in your code
-
-The pointer and the entry travel separately. See
-[How to read a referenced entry](/how-to/read-a-referenced-entry).
-
-## Related
-
-- [About content references](/explanation/content-references) — why a reference is a pointer.
-- [Models](/reference/dashboard/content/models) — the field and its options.
-- [Content entries](/reference/dashboard/content/content-entries) — the editor reference.

package/dist/docs/how-to/preview-a-workspace.md

@@ -1,28 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to see a preview of a workspace
-
-This guide shows you how to see an unpublished change on your own site before your
-visitors get it. You need a draft workspace with at least one change in it.
-
-## Steps
-
-1. Click **Preview** in the workspace toolbar.
-2. Enter the URL of your site.
-3. Set each feature flag to the **Default** value, to **On**, or to **Off**. This step
-   is optional.
-4. Click **Open preview**.
-
-Your site opens in a new tab with the unpublished workspace applied.
-
-The preview sends the workspace state to the SDK in the query parameters. The visitors on
-your live site therefore see no change.
-
-## Related
-
-- [About workspaces and versions](/explanation/workspaces-and-versions) — why a preview
-  cannot reach production.
-- [Workspaces](/reference/dashboard/workspaces) — the workspace states.

package/dist/docs/how-to/publish-a-workspace.md

@@ -1,30 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to publish a workspace
-
-This guide shows you how to make the changes in a workspace live. You need a draft
-workspace with at least one unpublished change.
-
-The **Publish** button is active only when the workspace holds an unpublished change. A
-badge in the toolbar shows the current state.
-
-## Steps
-
-1. Click **Publish** in the workspace toolbar.
-2. Read the change preview in the publish modal.
-3. Expand any modified row to see which properties changed.
-4. Read the banner above the diff, if one is there. It reports a change that breaks
-   another record.
-5. Click **Publish** to confirm.
-
-Picked makes an immutable snapshot of your workspace, and the SDK serves it to your
-visitors.
-
-## Related
-
-- [About workspaces and versions](/explanation/workspaces-and-versions) — why the modal
-  shows a diff.
-- [How to roll back a published version](/how-to/roll-back-a-published-version).

package/dist/docs/how-to/read-a-feature-flag.md

@@ -1,113 +0,0 @@
----
-type: how-to
-layout: docs
----
-
-# How to read a feature flag
-
-This guide shows you how to read the resolved bucket of a feature flag in your
-application. You need a feature flag in your project first, either from the dashboard or
-[defined in SDK code](/reference/sdk/features#define-a-feature-flag-in-sdk-code).
-
-Which accessor you pick decides *when* the visitor enters the test, so read
-[About feature flag allocation](/explanation/feature-flag-allocation) before you choose.
-
-## 1. Choose an accessor
-
-Each accessor returns a different value, and they differ in whether a read resolves the
-feature flag. A read that resolves the feature flag commits the visitor to a bucket and reports the
-decision.
-
-| API | Returns | Does a read resolve the feature flag? |
-| --- | --- | --- |
-| `useFeature` / `getFeature` | `() => Promise<bucket>` | Only when you call the function that it returns |
-| `useFeatureResult` / `getFeatureResult` | `{ id, bucket }`, and `undefined` until it resolves | Yes, as soon as the component renders |
-| `useFeatureEnabled` / `getFeatureEnabled` | `boolean \| undefined`, the dashboard **Enabled** setting | No |
-| `client.features.listStore` | Every registered feature flag, each with an `isResolved` property | No |
-| `client.features.getById(id)` | A store that holds one feature flag | No |
-
-Some decisions must wait for data that you do not have yet, such as a cart, a quote, or
-the profile of a signed-in user. For those, use `useFeature` or `getFeature`. Call the
-function they return after the data arrives.
-
-## 2. Read the bucket
-
-The bucket is what your site receives. A Boolean feature flag gives `true` or `false`. A
-Text feature flag gives the value of one variant, or `false` for the control group.
-
-:::code-group
-
-```tsx [React]
-import { useFeatureResult } from '@picked/react/hooks'
-
-function MyComponent() {
-  // { id, bucket }, or undefined until the feature flag resolves.
-  const result = useFeatureResult('hero')
-
-  return (
-    <div>
-      {result?.bucket === false && <p>Control</p>}
-      {result?.bucket === 'hero-a' && <p>Hero A</p>}
-      {result?.bucket === 'hero-b' && <p>Hero B</p>}
-    </div>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getFeatureResult } from '@picked/svelte/hooks'
-
-  // A store that holds { id, bucket }, or undefined until the feature flag resolves.
-  const result = getFeatureResult('hero')
-</script>
-
-{#if $result?.bucket === false}
-  <p>Control</p>
-{:else if $result?.bucket === 'hero-a'}
-  <p>Hero A</p>
-{:else if $result?.bucket === 'hero-b'}
-  <p>Hero B</p>
-{/if}
-```
-
-:::
-
-:::warning
-`useFeatureResult` and `getFeatureResult` resolve the feature flag as soon as the component
-renders, and they commit the visitor to a bucket at that moment.
-:::
-
-:::tip
-Run [type generation](/reference/sdk/type-generation) and `bucket` narrows to the values
-that this Text feature flag declares. Your editor then shows each value, and it reports a
-comparison against a value that the feature flag cannot serve.
-:::
-
-## 3. Read it without a framework
-
-The event bus works with any framework, and with none:
-
-```ts
-import { createClient } from 'picked'
-
-const client = createClient({
-  /* Put your client options here. */
-})
-
-client.eventBus.watch((event) => {
-  if (event.type === 'feature_decide' && event.feature.id === 'my-feature') {
-    console.log(event.feature) // { id: 'my-feature', key: 'v1', bucket: 'hero-a' }
-  }
-})
-```
-
-`feature_decide` fires only when the SDK makes a new decision. A visitor who returns
-restores the decision from storage and fires nothing, so watch
-`client.features.listStore` when you need the current state instead.
-
-## Related
-
-- [About feature flag allocation](/explanation/feature-flag-allocation) — when the
-  visitor enters the test.
-- [SDK feature flags](/reference/sdk/features) — the definition shape and the overrides.