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

package/dist/docs/explanation/the-content-model.md

@@ -5,52 +5,61 @@ layout: docs
 
 # About the content model
 
-Picked splits your content into three pieces: a layout, a section, and a content entry.
+Picked splits your content into three pieces: a Model, a Block, and a content entry.
 Why three, when a page editor needs only one?
 
 ## Schema and data are separate
 
-A **layout** is a schema. It sets which fields a piece of content can hold, and it holds
+A **Model** is a schema. It sets which fields a piece of content can hold, and it holds
 no data itself. A **content entry** is one instance of that schema, filled with real
 values.
 
-One layout backs many entries. Describe a campaign page one time, then make many pages
+One Model backs many entries. Describe a campaign page one time, then make many pages
 from it. Each entry carries its own title, its own body, and its own image, but they all
 share the shape.
 
 That split is also what lets your code depend on content that it never saw. Your component
-reads `content.title` because the layout promises a `title`. It works for every entry that
-comes from that layout.
+reads `content.title` because the Model promises a `title`. It works for every entry that
+comes from that Model.
 
-## A layout has a fixed category
+## A category gives a Model a role
 
-Each layout is a **page layout** or a **step layout**, and you choose which when you
-create it. The category cannot change later.
-
-| Layout | It gives shape to | Who renders it |
-| --- | --- | --- |
-| Page layout | A standalone [Page](/reference/dashboard/content/pages). | The SDK renders the entry on your server. |
-| Step layout | One [Step](/reference/dashboard/steps) inside a Flow. | The Step renders the entry in the browser. |
+A Model can carry a **category**, and the category decides what the Model gives its shape
+to. A **page layout** backs a standalone Page. A **step layout** backs one Step inside a
+Flow.
 
 The category is fixed because it decides where the SDK renders the entry. That is not a
-property you can change under an entry that exists already. See
-[About pages and flows](/explanation/pages-and-flows).
+property that you can change under an entry that exists already.
+
+A Model can also carry no category. Such a Model has no layout role, and nothing renders
+its entries directly. It holds the content that other content points at, such as a
+product or a category of your own. See
+[About content references](/explanation/content-references).
+
+The three roles are one machine. A layout is a Model with a job in the render path. A
+Model with no category is the same machine with no such job.
 
-## A section is a schema fragment
+## A Block is a schema fragment
 
-A layout gives shape to a whole page or a whole step. A **section** is a part that you put
-inside one or more layouts.
+A Model gives shape to a whole page or a whole step. A **Block** is a part that you put
+inside one or more Models.
 
-Define a hero one time as a section, then point at it from every page layout that needs
-one. Change the section and every layout that holds it changes with it.
+Define a hero one time as a Block, then point at it from every Model that needs one.
+Change the Block and every Model that holds it changes with it.
 
-This is the reason sections exist at all. Without them you must describe a common
-structure again in each layout, and the copies then become different. It is the same
+This is the reason Blocks exist at all. Without them you must describe a common
+structure again in each Model, and the copies then become different. It is the same
 argument for one fact in one place that runs through the rest of this documentation.
 
+A Block sits **inside** the entry that embeds it. It has no entry of its own, and no id
+that you can point at.
+
+That is the difference between a Block and a reference. A Block is a shape that many
+entries hold. A reference is a pointer at one entry that many entries share.
+
 ## Why a schema change does not migrate your data
 
-Change a layout or a section, and Picked does not rewrite the entries behind it. An entry
+Change a Model or a Block, and Picked does not rewrite the entries behind it. An entry
 that no longer matches its schema becomes invalid, and the dashboard shows an error on
 each field that does not fit.
 
@@ -58,20 +67,21 @@ That is deliberate. An automatic change must decide what a new required field ho
 every entry that came before it. Any value that it chooses is content that nobody wrote.
 Picked reports the error instead, and you correct it.
 
-The cost is real. After a schema change, check every entry that uses that layout and fix
+The cost is real. After a schema change, check every entry that uses that Model and fix
 each error before you publish. Picked serves valid content only, so an entry with an error
 does not reach a visitor.
 
 ## An error points at the exact field
 
 A validation error carries a path in JSON style, such as `sections[0].data.title`. The
-path holds through nested groups, repeated fields, and sections. An error inside a
+path holds through nested groups, repeated fields, and Blocks. An error inside a
 repeated group therefore tells you which item in that group holds it.
 
 ## Related
 
-- [Page and step layouts](/reference/dashboard/content/layouts) — every field type.
-- [Sections](/reference/dashboard/content/sections) — the reusable fragments.
+- [Models](/reference/dashboard/content/models) — every field type.
+- [Blocks](/reference/dashboard/content/blocks) — the reusable fragments.
 - [Content entries](/reference/dashboard/content/content-entries) — the editor and the
   validation.
-- [About pages and flows](/explanation/pages-and-flows) — which layout category you need.
+- [About content references](/explanation/content-references) — how one entry points at another.
+- [About pages and flows](/explanation/pages-and-flows) — which category you need.

package/dist/docs/how-to/create-a-content-entry.md

@@ -0,0 +1,48 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to create a content entry
+
+This guide shows you how to make one instance of a Model and fill it with data. You need
+a Model first. See [How to define a page layout](/how-to/define-a-page-layout).
+
+A Page makes its own entry when you create the page. Use this guide for the content that
+no Page and no Step owns, such as an author or a product.
+
+## 1. Open the entries list
+
+1. Open your workspace.
+2. Click **CMS** in the sidebar.
+3. Click **Content entries**.
+
+## 2. Create the entry
+
+1. Click **New content**.
+2. Choose the **Model** for the entry.
+3. Fill in each field. The form comes from the schema of the Model.
+4. Click **Create entry**.
+
+The Model is fixed when you create the entry. To move content to another Model, make a
+new entry and copy the values across.
+
+## 3. Correct every error
+
+An invalid field shows an error next to it while you edit. The error carries the path to
+the exact field. Correct each one before you publish, because Picked serves valid content
+only.
+
+## Find an entry again
+
+The entries list shows a title for each entry. The title is the first single-line text
+field of the entry. It shows the entry id when no such field holds a value.
+
+Use the **Model** filter to narrow the list to one Model.
+
+## Related
+
+- [Content entries](/reference/dashboard/content/content-entries) — the editor reference.
+- [Models](/reference/dashboard/content/models) — every field type.
+- [How to point one entry at another](/how-to/point-one-entry-at-another)
+- [How to publish a workspace](/how-to/publish-a-workspace)

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

@@ -5,8 +5,8 @@ layout: docs
 
 # How to define a page layout
 
-This guide shows you how to define the shape of a page. A layout sets which fields a page
-can hold, and it holds no data itself.
+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
 
@@ -19,7 +19,7 @@ can hold, and it holds no data itself.
 6. Add your fields. Choose a type for each one.
 7. Click **Create model**.
 
-The category is fixed when you create the layout. You cannot change it later.
+The category is fixed when you create the Model. You cannot change it later.
 
 ## Make a field repeatable
 
@@ -31,9 +31,16 @@ for a gallery, or for a list of features.
 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.
-- [Page and step layouts](/reference/dashboard/content/layouts) — every field type.
-- [How to reuse a section](/how-to/reuse-a-section).
+- [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/point-one-entry-at-another.md

@@ -0,0 +1,61 @@
+---
+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/read-a-referenced-entry.md

@@ -0,0 +1,111 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to read a referenced entry
+
+This guide shows you how to read the content that a
+[Reference field](/reference/dashboard/content/models#reference-fields) points at. You
+need a component that renders a step first. See
+[How to render a step form](/how-to/render-a-step-form).
+
+A Reference field holds a pointer, and not the content. The entry travels beside the
+content of the step, so you resolve the pointer against the content of the client.
+
+## 1. Resolve a single reference
+
+Pass the raw field value to `useReference()` in React, or to `getReference()` in Svelte.
+
+:::code-group
+
+```tsx [React]
+import { useUnit } from 'effector-react'
+import { useReference, useStepContent } from '@picked/react/hooks'
+
+export function ProductCategory() {
+  const content = useStepContent()
+  const category = useUnit(useReference(content?.category))
+
+  if (!category) return null
+
+  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>
+
+{#if $category}
+  <span>{$category.data.name ?? ''}</span>
+{/if}
+```
+
+:::
+
+In Svelte, pass a store and not a plain value. Content arrives after the component
+starts. A plain value therefore holds the result at "not set".
+
+## 2. Resolve a repeatable reference
+
+Use `useReferences()` or `getReferences()`. They give a list in field order.
+
+:::code-group
+
+```tsx [React]
+import { useUnit } from 'effector-react'
+import { useReferences, useStepContent } from '@picked/react/hooks'
+
+export function ProductCategories() {
+  const content = useStepContent()
+  const categories = useUnit(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, so you need no check for each item.
+
+## Handle a target that does not resolve
+
+A single reference gives an empty result when Picked cannot resolve the target. A
+repeatable reference leaves the item out of the list.
+
+This happens when somebody deleted the target, when the target belongs to another
+workspace, or when the chain of references is deeper than the limit.
+
+Render something else for the empty case, as the React example above does.
+
+## Related
+
+- [Content](/reference/sdk/content) — every hook and its return type.
+- [About content references](/explanation/content-references) — why the entry travels separately.
+- [How to point one entry at another](/how-to/point-one-entry-at-another) — the dashboard side.

package/dist/docs/how-to/reuse-a-section.md

@@ -6,27 +6,42 @@ layout: docs
 # How to reuse a section
 
 This guide shows you how to define a common structure one time and use it in more than
-one layout.
+one Model.
 
-## Create a section
+## 1. Create the section
 
-1. Open your workspace.
-2. Click **Pages** in the sidebar, then **Sections**.
+1. Click **Pages** in the sidebar.
+2. Click **Page Sections**.
 3. Click **New block**.
 4. Enter a **Name** and a **Key**.
 5. Add your fields.
 6. Click **Create block**.
 
-## Use it in a layout
+The **Category** is **Section** already, because you opened the list from **Page
+Sections**.
+
+## 2. Accept the section in a Model
 
 1. Open a page layout or a step layout.
-2. Add a **Section** field.
-3. Point that field at your section.
+2. Add a **Page Sections** field to the schema.
+3. Click **Save**.
+
+The field now accepts any Block of the Section category. Make the field repeatable to
+build a page from a list of sections.
+
+If you want one section at a fixed place instead of a list, add a **Content block** field.
+Set its **Block category** to the **Section** category.
+
+## 3. Choose the section in an entry
 
-The layout now carries the fields of the section at every place where that field appears.
+1. Open a content entry that uses the Model.
+2. Find the field that you added.
+3. Choose your Block.
+4. Fill in the fields of the Block.
+5. Click **Save**.
 
 :::warning
-An edit to a section does not migrate the entries that use it. Check each affected content
+An edit to a Block does not migrate the entries that use it. Check each affected content
 entry again, and correct every field error before you publish.
 :::
 
@@ -34,4 +49,5 @@ entry again, and correct every field error before you publish.
 
 - [About the content model](/explanation/the-content-model) — why a schema change does not
   migrate your data.
-- [Sections](/reference/dashboard/content/sections) — the reference.
+- [Blocks](/reference/dashboard/content/blocks) — the reference.
+- [Models](/reference/dashboard/content/models) — every field type.

package/dist/docs/index.md

@@ -25,7 +25,7 @@ Then:
 
 - **[Build](/how-to/create-an-experience)** — experiences, flows, conditions, and A/B
   tests.
-- **[Content](/how-to/define-a-page-layout)** — layouts, sections, pages, and assets.
+- **[Content](/how-to/define-a-page-layout)** — Models, Blocks, entries, pages, and assets.
 - **[Publish](/how-to/publish-a-workspace)** — preview, publish, and roll back.
 - **[Administer and measure](/how-to/invite-and-remove-members)** — members, API keys,
   analytics, and the tools that connect Picked to Google Tag Manager and to an AI tool.

package/dist/docs/reference/dashboard/content/blocks.mdx

@@ -0,0 +1,57 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Blocks
+
+A Block is a reusable schema fragment that you embed inside a Model, so that a common structure is defined one time.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/blocks"
+  alt="The blocks list in the schema builder on the Picked dashboard"
+/>
+
+## What a Block is
+
+A Block is a schema fragment with its own **Key**. A
+[Model](/reference/dashboard/content/models) gives its shape to a whole Page or Step. A
+Block is a part that you put into one or more Models. Define the shape one time, then
+reuse it everywhere.
+
+A Block holds no data of its own. The content that fills a Block sits inside the entry
+of the Model that embeds it.
+
+## Where a Block appears
+
+**CMS** in the sidebar holds **Blocks**, and that list shows every Block in the
+workspace. **Pages** holds **Page Sections**, which is the same list limited to the
+Section category.
+
+## Category
+
+| Category | What it does |
+| --- | --- |
+| **Section** | Marks the Block as a page section. A **Page Sections** field accepts it. |
+| **None (general content)** | Gives the Block no layout role. |
+
+The category is fixed when you create the Block. You cannot change it later.
+
+A **Content block** field holds the category of the Blocks that it accepts. Give that
+field the **Section** category to build a page section list.
+
+A field set to **Any category** accepts every Block in the workspace. This is the only
+kind of field that can hold a Block with no category.
+
+## Field types
+
+A Block holds the same field types as a Model. See
+[Field types](/reference/dashboard/content/models#field-types).
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why Blocks exist.
+- [How to reuse a section](/how-to/reuse-a-section)
+- [Models](/reference/dashboard/content/models)

package/dist/docs/reference/dashboard/content/content-entries.mdx

@@ -7,7 +7,7 @@ import { Screenshot } from '../../../../../components/Screenshot'
 
 # Content Entries
 
-A Content Entry is an instance of a layout filled with real data. A Page renders one entry; a Flow Step can render one too.
+A content entry is one instance of a Model, filled with real data. A Page renders one entry, and a Flow Step can render one too.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/content"
@@ -16,29 +16,80 @@ A Content Entry is an instance of a layout filled with real data. A Page renders
 
 ## What a content entry is
 
-A Content Entry is an instance of a layout's schema. The [layout](/reference/dashboard/content/layouts) defines the fields; the entry holds the actual values. One layout can back many entries, each with its own data.
+A content entry is an instance of the schema of a
+[Model](/reference/dashboard/content/models). The Model sets the fields, and the entry
+holds the values. One Model backs many entries, and each entry holds its own data.
+
+The Model of an entry is fixed when you create the entry.
+
+## The entries list
+
+**CMS** in the sidebar holds **Content entries**, with a count of every entry in the
+workspace.
+
+| Column | What it shows |
+| --- | --- |
+| Title | The value of the first single-line text field of the entry. It falls back to the entry id when no such field holds a value. |
+| Model | The Model that the entry belongs to. |
+| Entry ID | The stable id of the entry. |
+| Last updated | When somebody last saved the entry. |
+
+The **Model** filter narrows the list to one Model. The list has no search, because the
+title is derived at read time and is not a column that Picked can search.
 
 ## How entries bind to pages and steps
 
-A [Page](/reference/dashboard/content/pages) has a single Step, and that Step links to its entry through the layout content link. A Flow [Step](/reference/dashboard/steps) backed by a Step Layout binds an entry the same way. When the SDK renders the Page or Step, it resolves the linked entry and hands its data to your component.
+A [Page](/reference/dashboard/content/pages) has a single Step, and that Step links to
+its entry through the layout content link. A Flow [Step](/reference/dashboard/steps)
+with a Step Layout binds an entry the same way. When the SDK renders the Page or the
+Step, it resolves the linked entry and gives the data to your component.
 
 ## Edit entry data
 
-The entry editor renders a form from the layout schema. There is one input for each
-field, in the order that the schema sets. A repeatable field appears as a sortable
+The entry editor renders a form from the schema of the Model. There is one input for
+each field, in the order that the schema sets. A repeatable field shows as a sortable
 list. You can add to that list and put it into a new order. A group field holds its
 inputs under one heading.
 
+## Reference fields
+
+A [Reference field](/reference/dashboard/content/models#reference-fields) holds a pointer
+at another entry, and not a copy of it.
+
+| Control | What it does |
+| --- | --- |
+| **Choose entry** | Opens the entry picker. |
+| **Change entry** | Opens the entry picker on a field that holds a target already. |
+| **Clear** | Removes the pointer. It does not delete the entry. |
+
+The entry picker lists the entries that the **Target Model** of the field allows, and it
+has a search box. **Open model** opens the Model of an entry in a new tab.
+
 ## Validation
 
-Invalid data appears as an error on each field. The error carries a path in the JSON
-style, and it points at the exact place in the entry, for example
-`sections[0].data.title`. Fix every error before you publish, because Picked serves
+Invalid data shows as an error on each field. The error carries a path in the JSON style,
+and it points at the exact place in the entry, for example `sections[0].data.title`.
+
+A reference field reports an error when its target does not exist, or when the target
+belongs to the wrong Model. Fix every error before you publish, because Picked serves
 valid content only.
 
+## Delete rules
+
+Picked does not delete an entry while something still points at it.
+
+| Condition | Result |
+| --- | --- |
+| A Step uses the entry as its layout | The delete stops. |
+| Another entry points at it through a Reference field | The delete stops. |
+
+Clear the reference on the other entry first, then delete the target.
+
 ## Related
 
 - [About the content model](/explanation/the-content-model) — why the schema and the data
   are separate.
-- [How to fill and publish a page](/how-to/fill-and-publish-a-page)
-- [Page and step layouts](/reference/dashboard/content/layouts)
+- [About content references](/explanation/content-references) — why a delete stops.
+- [How to create a content entry](/how-to/create-a-content-entry)
+- [How to point one entry at another](/how-to/point-one-entry-at-another)
+- [Models](/reference/dashboard/content/models)