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

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

@@ -1,213 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Content
-
-The client holds every content record in one index, keyed by the id. The hooks on this
-page read that index.
-
-## The content record
-
-```ts
-interface Content {
-  id: string
-  contentModelKey?: string | null
-  data: Record<string, unknown>
-}
-```
-
-| Property | Type | Description |
-| --- | --- | --- |
-| `id` | `string` | The content entry id. |
-| `contentModelKey` | `string \| null` | The Key of the [Model](/reference/dashboard/content/models) that the entry belongs to. |
-| `data` | `Record<string, unknown>` | The field values, keyed by the field key from the schema. |
-
-The client registers the `content` array and the `references` array of the
-[experience content response](/reference/delivery-api/experience-content) into the same
-index. Your code can therefore read a referenced entry by its own id.
-
-## Read the content of a step
-
-`useStepContent()` in React, and `getStepContent()` in Svelte, give the `data` of the
-entry that the current step points at.
-
-:::code-group
-
-```tsx [React]
-import { useStepContent } from '@picked/react/hooks'
-
-export function Hero() {
-  const content = useStepContent()
-
-  return <h1>{String(content?.headline ?? '')}</h1>
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStepContent } from '@picked/svelte/hooks'
-
-  const content = getStepContent()
-</script>
-
-<h1>{$content?.headline ?? ''}</h1>
-```
-
-:::
-
-`useStepContent()` returns the data, and React re-renders the component when the data
-changes. `getStepContent()` returns a store, which you read with the `$` prefix.
-
-## Read a record by id
-
-`useContent(id)` and `getContent(id)` return a store of one record. The store holds
-`null` until the client registers that record.
-
-:::code-group
-
-```tsx [React]
-import { useContent, useStoreGlobal } from '@picked/react/hooks'
-
-export function Banner() {
-  const banner = useStoreGlobal(useContent('entry_42'))
-
-  return <h1>{String(banner?.data.headline ?? '')}</h1>
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getContent } from '@picked/svelte/hooks'
-
-  const banner = getContent('entry_42')
-</script>
-
-<h1>{$banner?.data.headline ?? ''}</h1>
-```
-
-:::
-
-## Resolve a reference field
-
-A [Reference field](/reference/dashboard/content/models#reference-fields) holds a pointer,
-and not the record. `useReference()` and `getReference()` resolve the pointer against the
-index.
-
-:::code-group
-
-```tsx [React]
-import { useReference, useStepContent, useStoreGlobal } from '@picked/react/hooks'
-
-export function ProductCategory() {
-  const content = useStepContent()
-  const category = useStoreGlobal(useReference(content?.category))
-
-  return <span>{String(category?.data.name ?? '')}</span>
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStepContent, getReference } from '@picked/svelte/hooks'
-
-  const content = getStepContent()
-  const category = getReference(content.map((c) => c?.category ?? null, { skipVoid: false }))
-</script>
-
-<span>{$category?.data.name ?? ''}</span>
-```
-
-:::
-
-For a repeatable Reference field, use `useReferences()` and `getReferences()`. They give
-a list in field order.
-
-:::code-group
-
-```tsx [React]
-import { useReferences, useStepContent, useStoreGlobal } from '@picked/react/hooks'
-
-export function ProductCategories() {
-  const content = useStepContent()
-  const categories = useStoreGlobal(useReferences(content?.categories))
-
-  return (
-    <ul>
-      {categories.map((category) => (
-        <li key={category.id}>{String(category.data.name ?? '')}</li>
-      ))}
-    </ul>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStepContent, getReferences } from '@picked/svelte/hooks'
-
-  const content = getStepContent()
-  const categories = getReferences(content.map((c) => c?.categories ?? null, { skipVoid: false }))
-</script>
-
-<ul>
-  {#each $categories as category (category.id)}
-    <li>{category.data.name ?? ''}</li>
-  {/each}
-</ul>
-```
-
-:::
-
-The list holds no empty places. A pointer that Picked cannot resolve is absent from the
-list, so each item is a record.
-
-:::note
-The Svelte helpers accept a store, and the examples pass one. Content arrives after the
-component starts. A plain value therefore holds the result at "not set".
-:::
-
-## Reference hooks
-
-| Hook | Returns | When the target is absent |
-| --- | --- | --- |
-| `useReference(value)` | `Store<Content \| null>` | `null` |
-| `useReferences(value)` | `Store<Content[]>` | The item is absent from the list. |
-| `getReference(value)` | `Store<Content \| null>` | `null` |
-| `getReferences(value)` | `Store<Content[]>` | The item is absent from the list. |
-
-Each one accepts the raw field value, or a store of it. A single value that goes to
-`useReferences()` or `getReferences()` gives a list of one.
-
-A target is absent for three reasons. Somebody deleted the entry, the entry belongs to
-another workspace, or the chain of references is deeper than the limit. See
-[About content references](/explanation/content-references).
-
-## Read a pointer directly
-
-`@picked/client` gives you the readers behind the hooks, for the code that runs outside
-React and Svelte.
-
-| Export | Returns | Description |
-| --- | --- | --- |
-| `isContentReference(value)` | `boolean` | Whether the value is a pointer. |
-| `readReferenceId(value)` | `string \| null` | The target id of a single pointer. |
-| `readReferenceIds(value)` | `string[]` | Every target id, for a repeatable field. |
-| `deriveReference(contents, value)` | `Store<Content \| null>` | The store behind `useReference` and `getReference`. |
-| `deriveReferences(contents, value)` | `Store<Content[]>` | The store behind `useReferences` and `getReferences`. |
-
-```ts
-import { createClient, readReferenceIds } from 'picked'
-
-const client = createClient({ projectId: 'proj_123' })
-const content = client.contents.getById('entry_789').getState()
-const categoryIds = readReferenceIds(content?.data.categories)
-```
-
-## Related
-
-- [About content references](/explanation/content-references) — why a reference is a pointer.
-- [How to read a referenced entry](/how-to/read-a-referenced-entry)
-- [Experience content endpoint](/reference/delivery-api/experience-content) — the wire shape.
-- [Server snapshot](/reference/sdk/ssr/serialize) — content on a server render.

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

@@ -1,51 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Experiences
-
-Define an experience in code with `createExperience()`. You can also load an
-experience from the dashboard at runtime with the
-[Dynamic Experiences Plugin](/reference/sdk/plugins/dynamic-experiences).
-
-The flow below points at a DOM selector and renders into it. A Page experience
-renders through a named slot instead. Point it at `.picked-slot-<name>` and render
-`<ExperienceSlot name="<name>" />` on your server. Use the slot path for a Page that
-the server renders and that search engines must read. Use the selector path for a
-Flow that the browser renders. See [Server-Side Rendering](/reference/sdk/ssr) and
-[Slots and Placements](/reference/sdk/ssr/slots-and-placements).
-
-## Create an experience
-
-```ts
-import { createExperience } from '@picked/client/plugins/create-experience'
-import { adaptSvelteComponent } from '@picked/svelte'
-import appCss from '../app.css?inline'
-
-export const productPageExperience = createExperience({
-  id: 'product-page-experience',
-  name: 'Product Page Experience',
-  condition: {
-    '==': [
-      { var: 'location.pathname' },
-      '/product/',
-    ],
-  },
-  targets: [{ selector: 'body', placement: 'after' }],
-  component: adaptSvelteComponent(
-    import('../ui/ProductPageExperience.svelte'),
-    { css: [appCss] },
-  ),
-})
-```
-
-To register an experience that you define in code, use the
-[Create Experience Plugin](/reference/sdk/plugins/create-experience). To read an experience from
-the dashboard at runtime and control it there, use the
-[Dynamic Experiences Plugin](/reference/sdk/plugins/dynamic-experiences).
-
-## Related
-
-- [About how Picked works](/explanation/how-picked-works) — the startup order.
-- [How to register a component](/how-to/register-a-component)

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

@@ -1,256 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Feature flags
-
-A feature flag lets you run an A/B test and roll a change out in stages. Control a
-feature flag from the dashboard, or define it in SDK code when you need your own decision
-rules.
-
-## Where feature flags come from
-
-You control most feature flags from the dashboard. The
-[dynamic experiences plugin](/reference/sdk/plugins/dynamic-experiences) reads the options of
-your project at runtime and registers every feature flag for you. You declare no feature flag in
-code.
-
-For a feature flag that you control from the dashboard, the SDK makes the definition:
-
-| Field | Value |
-| --- | --- |
-| `id` | The dashboard key of the feature flag |
-| `key` | `v{version}`, for example `v3` |
-| `name` | The dashboard name of the feature flag |
-| `enabled` | The dashboard **Enabled** toggle |
-| `weight` | The dashboard **Weight**, 0 to 100 |
-| `storage` | `local`, or `session` in [preview mode](/explanation/feature-flag-allocation#preview-mode) |
-| `decide` | Made by the SDK. See the two routes below. |
-
-The `decide` function that the SDK makes derives from the visitor ID and from the ID of
-the feature flag. A feature flag that you control from the dashboard therefore cannot use
-the data of your application. Define the feature flag in SDK code when you need that.
-
-Which route `decide` takes depends on the type of the feature flag:
-
-| Dashboard type | The bucket | How the SDK decides |
-| --- | --- | --- |
-| Boolean | `true` or `false` | It compares the stable value of the visitor against `weight`. |
-| Text | The value of one variant, or `false` | It compares the stable value of the visitor against the range that Picked gives to each variant. |
-
-The SDK sorts the variants by their key before it allocates, so the order of the payload
-has no effect. See
-[More than two groups](/explanation/feature-flag-allocation#more-than-two-groups).
-
-## Define a feature flag in SDK code
-
-Define your feature flags when you create the Picked client. Pass a `features` object. Use
-this when a decision needs data that only your application holds. Each feature flag needs a
-unique identifier, a version key, a name that a person can read, and a `decide`
-function:
-
-```ts
-import { createClient } from 'picked'
-
-const client = createClient({
-  projectId: 'your-project-id',
-  features: {
-    'summer-sale': {
-      key: 'summer-sale-v1', // The version key. Change it to invalidate the cache.
-      name: 'Summer Sale Experiment', // A name for analytics that a person can read.
-      decide: async () => {
-        // Put your decision rules here.
-        const isEligible = await checkUserEligibility()
-        return isEligible // Returns a boolean.
-      },
-      storage: 'local', // Optional: 'local' is the default, or 'session'.
-    },
-    'homepage-variant': {
-      key: 'homepage-test-v2',
-      name: 'Homepage A/B Test',
-      decide: async () => {
-        // Return a string for a test of more than two variants.
-        return Math.random() < 0.5 ? 'variant-a' : 'variant-b'
-      },
-    },
-  },
-})
-```
-
-A feature flag can also be a factory function, which starts the feature flag only when it is
-first needed:
-
-```ts
-features: {
-  'my-feature': () => ({
-    key: 'my-feature-v1',
-    name: 'My Feature',
-    decide: async () => true,
-  }),
-}
-```
-
-## Overrides in the URL
-
-You can override a feature flag decision from the URL search parameters, for a test:
-
-```
-https://example.com?picked-feature=my-feature:true
-```
-
-You can give more than one override value:
-
-```
-https://example.com?picked-feature=my-feature:true&picked-feature=homepage-variant:variant-a
-```
-
-The format is `?picked-feature=<feature-id>:<bucket-value>`. For a Text feature flag,
-give the value that the variant serves.
-
-A feature ID contains only lowercase letters, numbers, and hyphens. Therefore the SDK divides
-the parameter at the first colon. The bucket value can contain more colons:
-
-```
-https://example.com?picked-feature=opening-hours:09:00-17:00
-```
-
-This is useful for QA, because you can test one bucket value and change no code. The
-SDK keeps the override value in session storage. The browser clears it when you close
-the tab.
-
-When a URL parameter overrides a feature flag, the SDK registers that feature flag as
-enabled. Therefore `useFeatureEnabled` and `getFeatureEnabled` give `true`. A URL
-parameter can also override a feature flag that the dashboard **Enabled** toggle keeps
-off.
-
-## Use a feature flag in an experience condition
-
-You can use a feature flag in an experience condition through JSON logic:
-
-```ts
-const myExperience = createExperience({
-  // The other options go here.
-  condition: {
-    and: [
-      {
-        '==': [
-          {
-            invoke: {
-              var: 'features.summer-sale', // Point at the feature flag by its ID.
-            },
-          },
-          true, // Check that the bucket equals true.
-        ],
-      },
-    ],
-  },
-})
-```
-
-The ID in `features.<id>` is the **Key** of the feature flag from the dashboard. It is the
-same value that the detail page of the feature flag shows.
-
-An evaluation of a condition reads the bucket. Picked therefore allocates a visitor
-to a feature flag when the condition that points at it runs.
-
-## Watch for feature flag decisions
-
-Subscribe to the `feature_decide` event to track when a feature flag resolves:
-
-```ts
-client.eventBus.watch((event) => {
-  if (event.type !== 'feature_decide') return
-
-  const { feature } = event
-  console.log(`Flag "${feature.id}" resolved to bucket:`, feature.bucket)
-  // Example output: the feature flag resolved to the bucket true.
-
-  // Send the decision to your analytics.
-  analytics.track('Feature Decision', {
-    featureId: feature.id,
-    bucket: feature.bucket,
-  })
-})
-```
-
-A watch on `eventBus` reports only what happens after you subscribe.
-
-## Read the events that already happened
-
-`client.events` is a store of every event since the client started, in order. Each entry
-holds an `id`, the time `at`, and the `payload` that went on the bus.
-
-```ts
-const alreadyAllocated = client.events
-  .getState()
-  .filter((entry) => entry.payload.type === 'feature_decide')
-```
-
-Use it when your code starts after Picked does, and a `feature_decide` that you needed
-already happened before you subscribed.
-
-## Versions and cache invalidation
-
-The SDK caches a feature flag decision in browser storage. It uses `localStorage`, or
-`sessionStorage` in a preview. The cache key derives from the feature flag ID and the version,
-so a visitor keeps the same decision across page loads.
-
-:::note
-The SDK keeps a bucket value in storage as text. It reads `'true'` and `'false'` back as
-booleans. A variant with the name `true` or `false` therefore comes back as a boolean.
-Give each variant a different name.
-:::
-
-### How versions work
-
-A feature flag that you create in the dashboard starts at version 1. The SDK uses the
-version to build the cache key. A feature flag at version 3 caches under `v3`.
-
-The version affects **the cache only**. It is not part of the allocation. For a feature flag
-that you control from the dashboard, the allocation derives from the visitor ID and
-the weight of the feature flag.
-
-### What happens when you increment the version
-
-When you increment the version of a feature flag in the dashboard:
-
-1. **The cache key changes.** The old entry, `v3`, no longer matches the new key,
-   `v4`. The SDK therefore treats the feature flag as undecided.
-2. **The `decide` function runs again.** On the next page load, the SDK calls
-   `decide()` again and caches the new result.
-3. **Picked evaluates each visitor again and moves nobody.** For a feature flag that you
-   control from the dashboard the allocation is deterministic. The same visitor
-   against an unchanged weight gives the same bucket.
-
-:::note
-The new version clears the cached decisions and runs the allocation again. It moves
-no visitor between groups. With an unchanged weight, everybody lands where they were.
-Increment the version after you change a weight, so that Picked evaluates a visitor
-with a cached decision against the new weight.
-:::
-
-### The SDK `key` and the dashboard version
-
-For a feature flag that you define in SDK code, use the `key` field to set the version
-yourself. This applies when you do not read the feature flag from the dashboard:
-
-```ts
-features: {
-  'summer-sale': {
-    key: 'summer-sale-v2', // Change this to invalidate the cache.
-    // The other options go here.
-  },
-}
-```
-
-For a feature flag that you control from the dashboard, Picked sets the version for you. The
-dashboard adds the version number to the end of the cache key that the SDK uses.
-
-## Related
-
-- [How to read a feature flag](/how-to/read-a-feature-flag) — the accessors in use.
-- [About feature flag allocation](/explanation/feature-flag-allocation) — when a visitor
-  enters a test.
-- [Feature flags](/reference/dashboard/features) — the dashboard controls.
-