alinea 2.0.0-preview.13 → 2.0.0-preview.14

package/llms-full.txt

@@ -29,22 +29,22 @@ Navigate to the newly created project directory and install the package with you
 
 Variant: npm
 ```shellscript
-npm install alinea@preview
+npm install alinea@rc
 ```
 
 Variant: yarn
 ```shellscript
-yarn add alinea@preview
+yarn add alinea@rc
 ```
 
 Variant: pnpm
 ```shellscript
-pnpm add alinea@preview
+pnpm add alinea@rc
 ```
 
 Variant: bun
 ```shellscript
-bun add alinea@preview
+bun add alinea@rc
 ```
 
 ## 3. Initialize the project
@@ -53,7 +53,7 @@ Alinea requires a [config file](https://v2.alineacms.com/docs/configuration) whi
 
 Variant: npm
 ```shellscript
-npx alinea@preview init
+npx alinea@rc init
 ```
 
 Variant: yarn
@@ -231,15 +231,15 @@ The rest of this page is written for the agent. You are adding Alinea, a git-bas
 Install the package in the project root.
 
 ```shellscript
-npm install alinea@preview
+npm install alinea@rc
 ```
 
-With other package managers: `pnpm add alinea@preview`, `yarn add alinea@preview` or `bun add alinea@preview`.
+With other package managers: `pnpm add alinea@rc`, `yarn add alinea@rc` or `bun add alinea@rc`.
 
 ## 3. Run alinea init
 
 ```shellscript
-npx alinea@preview init
+npx alinea@rc init
 ```
 
 In a Next.js project `alinea init` creates:
@@ -1948,23 +1948,25 @@ This guide walks through moving an existing Alinea 1.7 project to 2.0. Your cont
 
 ## Checklist
 
-1. Run Node.js 24 or higher, locally, in CI and wherever your site runs, and use React 19.
-2. Update the package: `npm install alinea@preview` (or `pnpm add`, `yarn add`, `bun add`).
-3. Add `handlerUrl` to your config, it is now required. Replace `dashboardFile` with `adminPath`.
+1. Run Node.js 24 or higher, locally, in CI (scheduled jobs that run the alinea CLI too) and wherever your site runs, and use React 19.
+2. Update the package: `npm install alinea@rc` (or `pnpm add`, `yarn add`, `bun add`).
+3. Add `handlerUrl` to your config, it is now required, and set `baseUrl.production` (or make `handlerUrl` absolute). Replace `dashboardFile` with `adminPath`.
 4. Make sure your Next.js config is wrapped in `withAlinea` and your scripts run `alinea dev -- next dev` and `alinea build -- next build`: media URLs are now served through your site.
-5. Move children of `Config.media(...)` into its `children` option.
-6. Remove the options of `Field.metadata(...)` and the `step` option of `Field.time`.
-7. Rich text: pass `extensions` as a function and upgrade custom extensions to Tiptap 3.
-8. Handler: replace `remote` with `backend`, and move entry hooks to `beforeCommit` / `afterCommit`.
-9. Self-hosted OAuth2: provide `validateClaims`.
-10. Custom field views and dashboard code: import hooks from `alinea/cms` and components from `alinea/components` instead of `alinea/dashboard` and `alinea/ui`.
-11. Run `alinea build`, open the dashboard and save an entry to review the diff.
+5. Media: replace `image.url` with `image.src` and use the URLs Alinea returns instead of building them from `location`. `alinea build` warns about media files that store a url as their location, `alinea build --fix` repairs them.
+6. Move children of `Config.media(...)` into its `children` option.
+7. Remove the options of `Field.metadata(...)` and the `step` option of `Field.time`.
+8. Rich text: pass `extensions` as a function, upgrade custom extensions to Tiptap 3 and render custom attributes as `data-*` attributes.
+9. Handler: replace `remote` with `backend`, and move entry hooks to `beforeCommit` / `afterCommit`.
+10. Self-hosted OAuth2: provide `validateClaims`.
+11. Custom field views and dashboard code: import hooks from `alinea/cms` and components from `alinea/components` instead of `alinea/dashboard` and `alinea/ui`, replace `useEntryEditor` with `useEntry` and rename the theme tokens your CSS reads.
+12. Run `alinea build`, open the dashboard and save an entry to review the diff.
+13. Upgrading from a 2.0 preview instead? See [From a 2.0 preview](#from-a-2-0-preview).
 
 ## Runtime requirements
 
-Node.js 24 or higher. The CLI exits with "Alinea requires Node version 24 or higher" on older versions. The bundled content database is opened with Node's built-in `node:sqlite` (or `bun:sqlite` under Bun), so the runtime that serves your site needs Node 24 too, not only the machine that builds it.
+Node.js 24 or higher. The CLI exits with "Alinea requires Node version 24 or higher" on older versions. The bundled content database is opened with Node's built-in `node:sqlite` (or `bun:sqlite` under Bun), so the runtime that serves your site needs Node 24 too, not only the machine that builds it. The same goes for scheduled CI jobs that run the alinea CLI, such as a nightly `alinea build` or a script that imports content: update the Node version in those workflows as well.
 
-React 19. `react` and `react-dom` 19 are now peer dependencies and the CLI checks for them. In practice that means Next.js 15 or newer.
+React 19. `react` and `react-dom` 19 are now peer dependencies and the CLI checks for them. In practice that means Next.js 15 or newer. Check third-party React renderers too: libraries built on React 18 internals, such as older versions of react-three-fiber or react-pixi, break under React 19. Upgrade them to a version that supports React 19.
 
 ## Configuration
 
@@ -1994,6 +1996,23 @@ export const cms = createCMS({
 
 The handler now matches its path exactly, so requests have to use the configured URL (a trailing slash no longer matches).
 
+### baseUrl is required for production
+
+Your site reaches the handler at `handlerUrl` resolved against `baseUrl`, also in production, to check for new content. Without a production `baseUrl` (and with a relative `handlerUrl`), `alinea build` exits and queries throw `Missing baseUrl in Alinea config: set baseUrl.production to the url of your site`. Alinea doesn't fall back to the request origin or to hosting provider variables: set the production URL of your site yourself, for example from an environment variable you define:
+
+File: cms.ts
+```tsx
+export const cms = createCMS({
+  schema,
+  workspaces,
+  baseUrl: {
+    development: 'http://localhost:3000',
+    production: process.env.SITE_URL ?? 'https://example.com'
+  },
+  handlerUrl: '/api/cms'
+})
+```
+
 ### dashboardFile is replaced by adminPath
 
 `adminPath` is the path the dashboard is served on, `/admin` by default. `alinea build` writes the dashboard to `public/admin.html` and `withAlinea` serves it at `/admin`. `dashboardFile` still works when `adminPath` isn't set, but it is deprecated. See [Configuration](https://v2.alineacms.com/docs/configuration) for the new `maxUploadSize` and `tracer` options.
@@ -2014,6 +2033,28 @@ What to check:
 - Media requests now reach your handler route. A static export without the handler can't serve them.
 - If you defined `images.localPatterns` or `remotePatterns` yourself, check that the admin file route is still allowed. The `uploads.alinea.cloud` remote pattern is no longer added.
 - Don't change the `mediaDir` of an existing workspace: stored locations are relative to it. New projects default to `public/media`.
+- A media file whose `location` is a url (some 1.x saves wrote the upload url there) can't be served. `alinea build` warns about these files; `alinea build --fix` points them at the file of the same name in the `mediaDir` when there is one.
+
+Image links only have `src`: the `url` property, which held the same value, was removed so that spreading an image into `<img>` or `next/image` (`<Image {...image} />`) doesn't put a `url` attribute on the element. Replace `image.url` with `image.src`. File links keep `url` and `href`.
+
+Don't derive media URLs from the stored file. Code that reads `location`, or parses the 1.x file names (`name.<id>.ext`) to build a URL or find an id, breaks on `/admin/file/...` URLs. Use the URL Alinea returns instead: `src` for images, `url` (or `href`) for files, and `_url` when you query media files directly:
+
+```tsx
+import {cms} from '@/cms'
+import {Query} from 'alinea'
+import {MediaFile} from 'alinea/core'
+
+// 1.7: built the url from the stored location
+// const src = file.location
+
+const files = await cms.find({
+  type: MediaFile,
+  select: {title: Query.title, url: Query.url}
+})
+// Without a select each result has its url as `_url`
+```
+
+`ImageLink` no longer needs a type parameter when the image field has no extra fields: replace `ImageLink<undefined>` with `ImageLink`.
 
 A workspace can set `mediaUrl` to add a prefix to its media URLs, which helps when several workspaces have files with the same name.
 
@@ -2067,6 +2108,8 @@ Field.richText('Body', {
 
 The `RichText` renderer from `alinea/ui` always renders tables with a `<tbody>`, and the `tbody` view override is gone.
 
+Attributes that a custom extension adds to a node only reach your views and tag overrides of `RichText` as `data-*` attributes: render them as `data-*` in the extension's `renderHTML`. Content saved by 1.7 gets these attributes when it is saved again, see [Custom attributes](https://v2.alineacms.com/docs/fields/rich-text#custom-attributes).
+
 ### Edit.move
 
 ```tsx
@@ -2101,9 +2144,12 @@ const handler = createHandler({
     // Inspect or rewrite the changes, return the mutations to commit
     return mutations
   },
-  afterCommit({sha}) {
-    // Pages that query content refresh on their own, revalidate your own caches
-    revalidateTag('products', 'max')
+  afterCommit({entries, removed}) {
+    // Pages that query content refresh on their own, revalidate your own
+    // caches, eg. a feed that lists products
+    const changed = [...entries, ...removed]
+    if (changed.some(entry => entry.type === 'Product'))
+      revalidateTag('products', 'max')
   }
 })
 
@@ -2111,7 +2157,7 @@ export const GET = handler
 export const POST = handler
 ```
 
-Errors thrown in `afterCommit` are logged and don't fail the commit. See [Instant publishing](https://v2.alineacms.com/docs/instant-publishing).
+`afterCommit` receives the `mutations`, the `sha` of the new commit, the `user`, the changed `entries` as they are after the commit and the `removed` entries with the url they had. Errors thrown in it are logged and don't fail the commit. See [Instant publishing](https://v2.alineacms.com/docs/instant-publishing).
 
 ### remote is replaced by backend
 
@@ -2147,7 +2193,7 @@ The dashboard was rebuilt on React Aria Components. Nothing changes for editors
 
 ### Components
 
-`alinea/ui` now only exports the `RichText` renderer and the `imageBlurUrl` helper (and the deprecated `HStack`/`VStack`). Its `Button`, `Chip`, `Icon`, `Loader`, `Typo` and other components were removed, as were the files behind deep imports like `alinea/ui/Button`. Use the public component library instead, it is what the dashboard itself is built from:
+`alinea/ui` now only exports the `RichText` renderer and the `imageBlurUrl` helper (and the deprecated `HStack`/`VStack`, use `Stack` from `alinea/components`). Its `Button`, `Chip`, `Icon`, `Loader`, `Typo` and other components were removed, as were the files behind deep imports like `alinea/ui/Button`. Use the public component library instead, it is what the dashboard itself is built from:
 
 ```tsx
 // 1.7
@@ -2159,6 +2205,23 @@ import {Button, Spinner} from 'alinea/components'
 
 See [Components](https://v2.alineacms.com/docs/components). Dashboard icons are available from `alinea/dashboard/icons`.
 
+### Theme tokens
+
+The CSS custom properties of 1.7 were renamed and many were removed. Styles that read an old token silently fall back to the property's default. The closest replacements:
+
+- `--alinea-background` → `--alinea-bg`, `--alinea-content` → `--alinea-backdrop`, `--alinea-lift`, `--alinea-inner` and `--alinea-toolbar` → `--alinea-bg-muted`.
+- `--alinea-foreground` → `--alinea-fg`, `--alinea-foreground-faded` → `--alinea-fg-muted`, `--alinea-title-foreground` → `--alinea-fg-strong`.
+- `--alinea-outline` and `--alinea-inner-outline` → `--alinea-border`, `--alinea-highlight` → `--alinea-muted`.
+- `--alinea-fields` → `--alinea-input`, `--alinea-fields-foreground` → `--alinea-field-label`, `--alinea-fields-focus` and `--alinea-focus-foreground` → `--alinea-ring`.
+- `--alinea-selected` stays, `--alinea-selected-foreground` → `--alinea-selected-fg`, `--alinea-selected-faded` → `--alinea-primary-subtle`.
+- `--alinea-button-background` → `--alinea-primary`, `--alinea-button-foreground` → `--alinea-primary-fg`, `--alinea-error` → `--alinea-danger`.
+- `--alinea-accent` (the workspace color) → `--alinea-workspace-color`.
+- `--alinea-variant-info-*` → `--alinea-primary-subtle` and `--alinea-primary-subtle-fg`, `--alinea-variant-success-*` → `--alinea-success-subtle(-fg)`, `--alinea-variant-progress-*` → `--alinea-warning-subtle(-fg)`.
+- `--alinea-modal-background` → `--alinea-scrim`, `--alinea-shadow` → `--alinea-shadow-raised`, `--alinea-border-radius` → `--alinea-radius`.
+- Removed without a replacement: `--alinea-hue`, `--alinea-saturation`, `--alinea-positive`, `--alinea-negative`, `--alinea-button-hover`, `--alinea-accent-foreground`, `--alinea-divider-top`, `--alinea-divider-bottom`, `--alinea-tabs-trigger-*`, `--alinea-fields-table`, `--alinea-fields-header`, `--alinea-fields-shadow`, `--alinea-fields-selected` and the `create` and `disabled` variants. Derive hover and disabled shades with `color-mix()` and `opacity`.
+
+The tokens of `alinea/css`, and its resets, now apply inside elements with a `data-alinea-theme` attribute only. The dashboard sets it on `<html>`, so the CSS of your dashboard views reads the tokens as before. A page of your site that imports `alinea/css` to render `alinea/components` needs an element with `data-alinea-theme` around them. See [Theme tokens](https://v2.alineacms.com/docs/components#theme-tokens) for the full list.
+
 ### Custom field views
 
 Field views are still referenced by path (`view: '@/fields/Range.view'`) or passed as a component. The hooks and helpers for custom views now come from one entry point, `alinea/cms`. From `alinea/dashboard`, `useField` and its related hooks still work but are deprecated: the new `useField` returns a `[value, setValue]` tuple, and the options and error have their own hooks:
@@ -2175,11 +2238,11 @@ const options = useFieldOptions(field)
 const error = useFieldError(field)
 ```
 
-`useFieldValue`, `useFieldOptions`, `useFieldError` and `useFieldKey` move to `alinea/cms` too and `useFieldMutator` becomes `useFieldSetter`. Deep imports of dashboard hooks move as well: `useLocale` and `useGraph` from `alinea/dashboard/hook/*` are exported from `alinea/cms`, and `useEntryEditor` is replaced by `useEntry`. `alinea/dashboard/hooks` is internal now. `InputLabel` is now an alias of the `Field` component: it takes `label`, `description`, `error`, `required`, `disabled`, `readOnly`, `icon` and `shared`. Its 1.7 props `help`, `width`, `inline`, `size` and the fold props are gone, so help text passed through `{...options}` is no longer shown: pass it as `description`, or replace it with `FieldChrome` from `alinea/cms`, which reads the label, help text and error from the field. The form atoms (`useForm`, `FormProvider`, `FormRow` and so on) were removed from `alinea/dashboard`. See [Custom fields](https://v2.alineacms.com/docs/custom-fields) for a complete example.
+`useFieldValue`, `useFieldOptions`, `useFieldError` and `useFieldKey` move to `alinea/cms` too and `useFieldMutator` becomes `useFieldSetter`. Deep imports of dashboard hooks move as well: `useLocale` and `useGraph` from `alinea/dashboard/hook/*` are exported from `alinea/cms`, and `useEntryEditor` is replaced by `useEntry`. `useEntryEditor` still works as a shim for views that only read the entry: its `activeVersion` has the `id`, `locale`, `path`, `status`, `title` and `type` of the entry, and `activeVersion.data` only has `path`. Reading another property throws, read field values with `useFieldValue(field)` instead. `alinea/dashboard/hooks` is internal now. `InputLabel` is now an alias of the `Field` component: it takes `label`, `description`, `error`, `required`, `disabled`, `readOnly`, `icon` and `shared`. Its 1.7 props `help`, `width`, `inline`, `size` and the fold props are gone, so help text passed through `{...options}` is no longer shown: pass it as `description`, or replace it with `FieldChrome` from `alinea/cms`, which reads the label, help text and error from the field. The form atoms (`useForm`, `FormProvider`, `FormRow` and so on) were removed from `alinea/dashboard`. See [Custom fields](https://v2.alineacms.com/docs/custom-fields) for a complete example.
 
 ### Custom type views
 
-A type's `view` now only receives `{type}`, the `editor` prop of 1.7 is gone. A custom `auth` view in the config is not used: the dashboard always renders its own sign-in.
+A type's `view` now only receives `{type}`, the `editor` prop of 1.7 is gone. The view no longer replaces the whole editor: it renders below the entry header, which publishes and saves drafts, and reads and writes the fields of the entry with the hooks of `alinea/cms`. A custom `auth` view in the config is not used: the dashboard always renders its own sign-in.
 
 ### List overviews
 
@@ -2226,6 +2289,24 @@ See [Overviews](https://v2.alineacms.com/docs/overviews) for sorting, custom cel
 
 `alinea/yjs` and `alinea/cloud/view/CloudAuth` no longer exist. `alinea/picker/entry/EntryPicker` and `alinea/picker/url/UrlPicker` no longer ship the picker UI: `EntryPickerModal`, `UrlPickerForm` and `UrlPickerModal` were removed without a public replacement. Import the picker option types (`EditorInfo`, `EditorLocation`, `EditorLimitLocation` and `EntryPickerConditions`) from `alinea/field/link`. Code that subclassed fields relied on the removed shape system (`alinea/core/Shape`, `Field.shape`, `Type.shape`): the field constructors no longer take a shape, and `postProcess` became `queryValue`.
 
+## From a 2.0 preview
+
+Projects on a 2.0 preview have most of the above already. These changes landed in the release candidate:
+
+- Image links no longer have `url`, use `src`. File links keep `url` and `href`.
+- `useEntry()` from `alinea/cms` returns a `DashboardEntry`: the `id`, `type`, `title`, `path`, `url`, `locale`, `status`, `workspace`, `root` and `parentId` of the entry and its saved field values in `data`. The other properties of the internal entry row are gone.
+- `useEntryEditor()`: the publish status moved from `activeVersion.data.status` to `activeVersion.status`. Reading another property of `activeVersion.data` than `path` throws.
+- `useSiblingFieldValue(key)` is deprecated: pass the field to `useFieldValue(field)`, which is typed and also reads fields of a parent row or the entry, or its key: `useFieldValue('path')`. `EditFields` takes an object field to render its fields in its scope.
+- Theme tokens apply inside `data-alinea-theme` only, see [Theme tokens](#theme-tokens) above. The workspace color is `--alinea-workspace-color`.
+- `Select` from `alinea/components` only shows its clear button with `clearable`. `Field.select` still lets editors clear fields that aren't required.
+- `Select`, `ComboBox` and `MultipleSelect` values are strings or numbers, and `onValueChange` is typed like the `value` you pass. Without a `value`, it receives `string | number`.
+- `TimeField` with a `name` submits `14:30` (or `14:30:15` with `granularity="second"`) like a native time input, it used to submit seconds always.
+- `NumberField` no longer groups digits: pass `formatOptions={{useGrouping: true}}` to show `1,250`.
+- `afterCommit` also receives the changed `entries` and the `removed` entries, so hooks no longer have to look them up from the mutations.
+- Every field accepts `width`, custom fields don't need to declare it in their options.
+- `alinea build` accepts an absolute `handlerUrl` without a production `baseUrl`, and its error names the missing `baseUrl` setting.
+- A type's `view` renders below the entry header, in the editor of the entry: the field hooks of `alinea/cms` and `EditField` edit its fields and the header publishes them. It used to replace the whole editor without access to the fields.
+
 ## After upgrading
 
 Run your build and open the dashboard. Things to try: an image renders on your site through `/admin/file/...`, publishing an entry updates the site, and custom fields still render. Then have a look at what's new in 2.0: [Field.localiser](https://v2.alineacms.com/docs/internationalization) for per-field translations, URL aliases and backlinks, [instant publishing](https://v2.alineacms.com/docs/instant-publishing) and the [MCP server](https://v2.alineacms.com/docs/mcp) for coding agents.
@@ -2403,6 +2484,7 @@ The label ("Author") is what editors see. The name the type is stored under is i
 ## Options
 
 - `fields` (required): the [fields](https://v2.alineacms.com/docs/fields) of the type, keyed by name. Field names must start with a letter and contain only letters, digits and underscores. Spread [tabs](https://v2.alineacms.com/docs/fields/tabs) or `Field.view(...)` sections in between to lay out the form.
+- `settings`: fields that editors set in the settings sheet of a block, below its label and anchor, instead of in the block's form. Entries of the type show them in a Settings tab. They are stored and queried like the other fields, so their names can't repeat a field name.
 - `contains`: the types that can be created as children of this entry, by schema name or by reference. Without it, entries of this type can't have children.
 - `overview`: how the dashboard lists the children: columns, the default order (`sort`), the layout and actions. See [Overviews](https://v2.alineacms.com/docs/overviews).
 - `insertOrder`: where new children are added: `'first'`, `'last'` or `'free'` (default), which lets the editor choose in the create dialog.
@@ -2411,7 +2493,8 @@ The label ("Author") is what editors see. The name the type is stored under is i
 - `hidden`: set to `true` to leave entries of this type out of the sidebar tree. They can still be linked to and queried.
 - `defaultView`: `'edit'` opens the form when an entry is selected, `'overview'` shows a table of its children first. The default is `'overview'` for entries that have children and `'edit'` otherwise.
 - `preview`: turn [live previews](https://v2.alineacms.com/docs/live-previews) on or off for this type (`true`/`false`), or pass a React component that renders the preview. It overrides the setting of the root, workspace and config.
-- `view`: a React component, or a path to one, that replaces the entry editor for this type. It receives `{type}`.
+- `view`: a React component, or a path to one, that replaces the form of entries of this type. It renders below the entry header and edits the entry with the hooks of `alinea/cms`. It receives `{type}`. See [Replace the form of a type](https://v2.alineacms.com/docs/custom-fields#replace-the-form-of-a-type).
+- `actions`: components rendered in the header of the entry editor, next to the publish button, such as an export button. Each is a component or a path to one and receives `EntryActionProps`: the `entry` and the `locale` it is edited in. See [Add actions to the entry header](https://v2.alineacms.com/docs/custom-fields#add-actions-to-the-entry-header).
 - `orderChildrenBy` (deprecated): sort children by one or more fields. Use `overview.sort`, which still accepts the same value.
 - `summaryRow`, `summaryThumb` (deprecated): not used by the dashboard. Configure the columns and card image in the `overview` of the parent instead.
 
@@ -2572,6 +2655,8 @@ export const Home = Config.document('Home', {
 })
 ```
 
+Next to `fields`, a document takes `seo` and `details`: fields added to the SEO and Details tabs. `settings` adds a Settings tab with its fields.
+
 ## Using the metadata
 
 Select the metadata field in the query for a page and map it to your framework's head tags. With the Next.js App Router:
@@ -3155,6 +3240,37 @@ export function Prose({doc}: {doc: TextDoc}) {
 
 The overridable tags are `h1`–`h6`, `p`, `b`, `i`, `ul`, `ol`, `li`, `blockquote`, `hr`, `img`, `br`, `small`, `sub`, `sup`, `a`, `table`, `tr`, `td` and `th`. Pass `text` to wrap every piece of text in a component. Headings get an `id` (the anchor an editor set, or a slug of the heading text), so you can link to sections.
 
+### Custom attributes
+
+Attributes that a custom extension adds to a node are stored with the node, but only the `data-*` attributes its `renderHTML` produces reach the rendered elements and your tag overrides. Render an attribute as `data-*` to use it on your site:
+
+```tsx
+import {Field} from 'alinea'
+import {extensions} from 'alinea/field/richtext'
+
+const Checklist = extensions.BulletList.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      checklist: {
+        default: null,
+        renderHTML: attributes =>
+          attributes.checklist ? {'data-checklist': 'true'} : {}
+      }
+    }
+  }
+})
+
+export const body = Field.richText('Body', {
+  extensions: defaults => ({...defaults, BulletList: Checklist})
+})
+
+// <RichText doc={body} ul={<ul className="list" />} /> renders
+// <ul data-checklist="true" class="list">
+```
+
+Content saved by Alinea 1.x only has the raw attribute (`checklist: true`). Its `data-*` attribute is added when the entry is saved again in the dashboard, until then views don't receive it.
+
 ### Blocks
 
 Blocks are rendered only when you pass a component for their type name. The component receives the block's fields as props:
@@ -3304,6 +3420,25 @@ export default Config.type("List field", {
 
 Row types are ordinary [Types](https://v2.alineacms.com/docs/schema/type): they can have tabs, an `icon` that is shown in the add menu and nested lists. They don't need a title or path and don't have to be in the schema.
 
+Options that change how a block looks rather than what it says, such as a background or a layout variant, can go in the type's `settings`. Editors find them in the block's settings sheet, below the label and anchor, which keeps the block form short. They're stored on the row next to its other fields:
+
+```tsx
+const HeroBlock = Config.type('Hero', {
+  fields: {
+    title: Field.text('Title'),
+    text: Field.richText('Text')
+  },
+  settings: {
+    background: Field.select('Background', {
+      options: {light: 'Light', dark: 'Dark'},
+      initialValue: 'light'
+    })
+  }
+})
+
+// A queried row: {_type: 'HeroBlock', title, text, background, ...}
+```
+
 ## Value
 
 The value is an array of rows. Next to its fields, every row has:
@@ -3807,11 +3942,11 @@ An object with a key per field: `{street: '', zip: '', city: ''}`. New entries s
 
 ## Querying
 
-Select and sort on the object as a whole: the inner fields aren't registered in the schema, so `Venue.address.city` can't be used in `select` or `orderBy`. To filter on an inner value, use `has`:
+Without a `select` the object is returned as a whole. Select or sort on a field inside it through the object, `Venue.address.city`, and filter on inner values with `has`:
 
 ```tsx
 import {cms} from '@/cms'
-import {Config, Field} from 'alinea'
+import {Config, Field, Query} from 'alinea'
 
 export const Venue = Config.document('Venue', {
   fields: {
@@ -3827,8 +3962,10 @@ export const Venue = Config.document('Venue', {
 const venuesInGhent = await cms.find({
   type: Venue,
   filter: {address: {has: {city: 'Ghent'}}},
-  select: {address: Venue.address}
+  select: {title: Query.title, street: Venue.address.street},
+  orderBy: {asc: Venue.address.street}
 })
+// Array<{title: string, street: string}>
 ```
 
 ## Reusing a group of fields
@@ -4304,7 +4441,6 @@ The picker only offers images: files with an extension such as `.jpg`, `.png`, `
 Each image is resolved to an `ImageLink`:
 
 - `src`: the url of the image on your site, such as `/admin/file/landscape.jpg?v=3f2a…`. It's served through your Alinea handler, and the `v` parameter changes when the file is replaced, so caches never serve an outdated copy.
-- `url`: the same as `src`.
 - `width` and `height`: the dimensions in pixels.
 - `alt`: the alt text editors enter in the media library, in the locale of the entry you queried when the media root is [translated](https://v2.alineacms.com/docs/workspaces/media).
 - `focus`: the focal point as `{x, y}`, each between 0 and 1. Use it as `object-position` when you crop the image.
@@ -4759,7 +4895,58 @@ const urls = await cms.find({type: BlogPost, select: Query.url})
 // Array<string>
 ```
 
-`Query` has `id`, `title`, `type`, `index`, `workspace`, `root`, `status`, `parentId`, `locale`, `path`, `url`, `aliases`, `createdAt` and `updatedAt`, plus the relation helpers such as `Query.children` described in [Related content](https://v2.alineacms.com/docs/query/related) and `Query.snippet` for [search results](https://v2.alineacms.com/docs/query/filtering).
+`Query` has `id`, `title`, `type`, `index`, `workspace`, `root`, `status`, `parentId`, `locale`, `path`, `url`, `aliases`, `createdAt` and `updatedAt`, plus the relation helpers such as `Query.children` and `Query.referencedBy` described in [Related content](https://v2.alineacms.com/docs/query/related) and `Query.snippet` for [search results](https://v2.alineacms.com/docs/query/filtering).
+
+### Query fields and type fields
+
+There are two kinds of references you can select. `Query.*` are the built-in properties every entry has, whatever its type: `Query.id`, `Query.title`, `Query.url` and the others above. The fields you define are selected through their type: `BlogPost.intro` is the `intro` field of `BlogPost`, `BlogPost.cover` its cover image. Type fields are typed from their definition and resolved like they are without a select, so `BlogPost.cover` returns an `ImageLink`. Combine both in one `select`:
+
+```tsx
+import {cms} from '@/cms'
+import {BlogPost} from '@/schema'
+import {Query} from 'alinea'
+
+const posts = await cms.find({
+  type: BlogPost,
+  select: {
+    // Built-in properties of the entry
+    id: Query.id,
+    title: Query.title,
+    url: Query.url,
+    // Fields of the BlogPost type
+    intro: BlogPost.intro,
+    cover: BlogPost.cover
+  }
+})
+// Array<{id: string, title: string, url: string, intro: string, cover: ImageLink | null}>
+```
+
+A type field only has a value on entries of that type, so select it in a query for that `type` (or one filtered on `_type`). `Query` fields work in any query, also one without a `type`, such as a search across all entries. Fields that `Config.document` adds, like `title` and `path`, are available both ways: `Query.title` and `BlogPost.title` return the same value.
+
+Fields inside an [object field](https://v2.alineacms.com/docs/fields/object) are selected through the object: `Page.seo.title` returns the `title` of the `seo` object, typed like the field. That works wherever a field can be selected, also inside relations such as `Query.children`, and in `orderBy`:
+
+```tsx
+import {cms} from '@/cms'
+import {Config, Field, Query} from 'alinea'
+
+export const Page = Config.document('Page', {
+  fields: {
+    seo: Field.object('SEO', {
+      fields: {
+        title: Field.text('SEO title'),
+        description: Field.text('SEO description')
+      }
+    })
+  }
+})
+
+const pages = await cms.find({
+  type: Page,
+  select: {url: Query.url, title: Page.seo.title},
+  orderBy: {asc: Page.seo.title}
+})
+// Array<{url: string, title: string}>
+```
 
 Selecting only what a page needs keeps the data you pass to client components small, and TypeScript infers the result either way. To name the type of a result, use `Awaited<ReturnType<typeof yourQueryFunction>>`.
 
@@ -5004,6 +5191,7 @@ A filter is an object with a condition per key. The keys are:
 
 - the fields of the queried `type`, such as `featured` or `publishDate`. TypeScript checks them when you pass a `type`.
 - the entry's own properties with an underscore: `_id`, `_type`, `_parentId`, `_path`, `_url`, `_status`, `_locale`, `_workspace`, `_root`, `_index`, `_createdAt` and `_updatedAt`.
+- `_referenced`: whether another entry links to the entry. `true` or `false`, or a `Query.referencedBy(...)` query that the linking entry has to match, see [Entries that link here](https://v2.alineacms.com/docs/query/related#entries-that-link-here).
 
 Every key has to match, so several keys in one filter mean "and".
 
@@ -5135,6 +5323,7 @@ export async function searchSite(terms: string, locale: string) {
 How it matches:
 
 - The input is split into words, and an entry must match every word.
+- Hyphenated, spaced and joined spellings find each other: `multi-modal`, `multi modal` and `multimodal` all match "multi-modal", "multi modal" and "multimodal".
 - Words match as prefixes, so `alin` finds "Alinea".
 - Small typos are tolerated: one wrong letter for words of 5 to 14 characters, more for longer words. Case and accents don't matter.
 - Entry titles are always searched. Other fields only when you mark them `searchable: true`: [text](https://v2.alineacms.com/docs/fields/text) and [rich text](https://v2.alineacms.com/docs/fields/rich-text) fields support it, also inside lists, objects and rich text blocks.
@@ -5143,7 +5332,7 @@ How it matches:
 `Query.snippet(start, end, cutOff, limit)` returns a short excerpt of the searchable text around the matches, with matches wrapped in `start` and `end`. The defaults are `'<mark>'`, `'</mark>'`, `'...'` and 64, and `limit` (the length in words) can be at most 64. It can only be used together with `search`. The excerpt is plain text from your content: escape it, or render the markers yourself instead of using `dangerouslySetInnerHTML`.
 
 ### Related (https://v2.alineacms.com/docs/query/related)
-A single query can also fetch entries related to the ones it finds: their parents, children and siblings, their translations, and the entries they link to. Put a relation in `select` (or in `include` when you don't select), and it's resolved in the same query.
+A single query can also fetch entries related to the ones it finds: their parents, children and siblings, their translations, the entries they link to and the entries that link to them. Put a relation in `select` (or in `include` when you don't select), and it's resolved in the same query.
 
 ```tsx
 import {cms} from '@/cms'
@@ -5243,9 +5432,9 @@ const post = await cms.get({
 
 Linked entries are looked up in the locale of the entry you queried, falling back to entries without a locale, so a link to an untranslated author keeps working from every translation of a post.
 
-## The other direction
+## Entries that link here
 
-Links are stored on the entry that links, so "all posts by this author" is a filter on the posts. Filter on the id of the target, stored as `_entry`:
+Links are stored on the entry that links. `Query.referencedBy` finds the entries that link to the entry, through any of their fields, including links in rich text. Pass `type` to only find entries of that type, and `field` to only follow one link field of it. Like the other relations it takes the query options, `count: true` and `first: true`:
 
 ```tsx
 import {cms} from '@/cms'
@@ -5253,19 +5442,68 @@ import {Author, BlogPost} from '@/schema'
 import {Query} from 'alinea'
 
 export async function authorPage(path: string) {
-  const author = await cms.get({
+  return cms.get({
     type: Author,
     path,
-    select: {id: Query.id, name: Query.title, bio: Author.bio}
+    select: {
+      name: Query.title,
+      bio: Author.bio,
+      // The posts whose author field links to this author
+      posts: Query.referencedBy({
+        type: BlogPost,
+        field: BlogPost.author,
+        select: {title: Query.title, url: Query.url},
+        orderBy: {desc: BlogPost.publishDate}
+      }),
+      // Every entry linking to the author, in any field
+      mentions: Query.referencedBy({count: true})
+    }
   })
-  const posts = await cms.find({
+}
+```
+
+The entries that link to a translated entry are looked up in its locale. For an entry without a locale, such as a shared author, the linking entries of every locale are returned: pass `locale` to only get those of one locale.
+
+The same relation is a filter condition: `_referenced` holds for entries that an entry of the query links to. `{_referenced: true}` matches entries that anything links to and `{_referenced: false}` entries nothing links to, such as unused media files:
+
+```tsx
+import {cms} from '@/cms'
+import {Author, BlogPost} from '@/schema'
+import {Query} from 'alinea'
+
+// Authors of at least one featured post
+const featuredAuthors = await cms.find({
+  type: Author,
+  filter: {
+    _referenced: Query.referencedBy({
+      type: BlogPost,
+      field: BlogPost.author,
+      filter: {featured: true}
+    })
+  },
+  select: Query.title
+})
+```
+
+### Filtering on the link
+
+The other way around, "the posts by this author" is a filter on the posts: links store the id of their target as `_entry`. This is the way to go when you start from the posts, for example to page through them:
+
+```tsx
+import {cms} from '@/cms'
+import {BlogPost} from '@/schema'
+import {Query} from 'alinea'
+
+export async function postsBy(authorId: string, page: number) {
+  return cms.find({
     type: BlogPost,
     // Single link: has, multiple links: includes
-    filter: {author: {has: {_entry: author.id}}},
+    filter: {author: {has: {_entry: authorId}}},
     select: {title: Query.title, url: Query.url},
-    orderBy: {desc: BlogPost.publishDate}
+    orderBy: {desc: BlogPost.publishDate},
+    skip: page * 10,
+    take: 10
   })
-  return {author, posts}
 }
 ```
 
@@ -5790,6 +6028,8 @@ Diagram: Publish flow: the dashboard publishes to your site's handler, which com
 
 ## Skip builds for content-only commits
 
+Only set this up once your deployed site has a backend that syncs content at runtime: Alinea Cloud or a self-hosted backend. Without one, a deployment is how new content reaches your site, so skipping content-only builds would leave published changes offline.
+
 Because content is synced at runtime, a commit that only changes content does not need a new deployment. On Vercel you can skip those builds with an `ignoreCommand` in `vercel.json`. The command exits successfully, which tells Vercel to skip the build, when nothing outside the `content` directory changed since the last deployment. Comparing against `VERCEL_GIT_PREVIOUS_SHA` covers every commit in a push, not only the last one; on the first deployment of a branch it falls back to the previous commit:
 
 File: vercel.json
@@ -5803,9 +6043,28 @@ Note (info): Adjust `content` if your content lives in a different directory.
 
 ## Static pages
 
-Static pages are revalidated for you. Every page that queries content is tagged, and after each commit the handler marks those pages as stale. The next visit is still answered from the cache while Next.js rebuilds the page in the background, and the visit after that gets the new content. No visitor waits for a render, and no `revalidatePath` call is needed.
+Static pages are revalidated for you. Every page that queries content is tagged, and after each commit the handler marks those pages as stale. The next visit is still answered from the cache while Next.js rebuilds the page in the background, and the visit after that gets the new content. No visitor waits for a render, and no `revalidatePath` call is needed. This includes pages generated with `generateStaticParams`: revalidation code in `afterCommit` that refreshes them by hand, such as `revalidateTag('_N_T_/layout')` or `revalidatePath('/', 'layout')`, can be removed.
+
+Pages rendered at request time sync on their next render. The first one after a commit can still show the previous version while the shared content sha refreshes. Content pushed to your repository without the dashboard, for example a local edit, skips the handler: pages pick it up within five minutes, or within `syncInterval` seconds when your config sets it. Use the handler's `afterCommit` hook if other caches in your app depend on content, for example your own `fetch` tags. It receives the changed `entries` and the `removed` ones, see [Commit hooks](page:guides/deploy#commit-hooks):
+
+File: app/(alinea)/api/cms/route.ts
+```tsx
+import {cms} from '@/cms'
+import {createHandler} from 'alinea/next'
+import {revalidateTag} from 'next/cache'
+
+const handler = createHandler({
+  cms,
+  afterCommit({entries, removed}) {
+    const changed = [...entries, ...removed]
+    if (changed.some(entry => entry.type === 'Product'))
+      revalidateTag('products', 'max')
+  }
+})
 
-Pages rendered at request time sync on their next render. The first one after a commit can still show the previous version while the shared content sha refreshes. Content pushed to your repository without the dashboard, for example a local edit, skips the handler: pages pick it up within five minutes, or within `syncInterval` seconds when your config sets it. Use the handler's `afterCommit` hook if other caches in your app depend on content, for example your own `fetch` tags.
+export const GET = handler
+export const POST = handler
+```
 
 ### Editing content (https://v2.alineacms.com/docs/editing-content)
 Your `cms` instance can create, update, publish and delete entries from code, for example to import content from another system or to seed a new project. Changes go through your handler, like saves in the dashboard: during development they are written to your content files.
@@ -6631,7 +6890,7 @@ Without a `backend` option the handler connects to Alinea Cloud. Pass `backend`
 
 ### Commit hooks
 
-Two hooks on the handler run for every commit, whatever it contains. `beforeCommit` receives the changes before they are committed: inspect or rewrite them and return the mutations to commit, or return nothing to keep them as they are. `afterCommit` runs once the commit is made, with the mutations and the `sha` of the new commit: revalidate caches of your own, notify your team or trigger a deploy.
+Two hooks on the handler run for every commit, whatever it contains. `beforeCommit` receives the changes before they are committed: inspect or rewrite them and return the mutations to commit, or return nothing to keep them as they are. `afterCommit` runs once the commit is made, with the mutations, the `sha` of the new commit, the changed `entries` as they are after the commit and the `removed` entries with the url they had: revalidate caches of your own, notify your team or trigger a deploy.
 
 File: app/(alinea)/api/cms/route.ts
 ```tsx
@@ -6645,9 +6904,12 @@ const handler = createHandler({
     // Inspect or rewrite the changes, return the mutations to commit
     return mutations
   },
-  afterCommit({sha}) {
-    // Pages that query content refresh on their own, revalidate your own caches
-    revalidateTag('products', 'max')
+  afterCommit({entries, removed}) {
+    // Pages that query content refresh on their own, revalidate your own
+    // caches, eg. a feed that lists products
+    const changed = [...entries, ...removed]
+    if (changed.some(entry => entry.type === 'Product'))
+      revalidateTag('products', 'max')
   }
 })
 
@@ -6738,6 +7000,8 @@ When two parts implement the same thing, the one listed last wins. That is how a
 
 Commits are made by the owner of the token. The editor who published is added as a `Co-authored-by` trailer with their name and email. When the branch moved since the dashboard last synced, the handler syncs and retries the commit up to three times.
 
+To commit under another name, such as when your host only deploys commits of its members, pass `author: {name, email}`. GitHub links the commit to the account that owns the email. These commits are written through the REST API: GitHub does not mark them as verified, and a save usually spends three REST requests, plus one per uploaded file, where commits by the token owner spend none. Removing a file that is already gone costs one more, and when the branch moved in the meantime the save is repeated.
+
 ## Authentication
 
 ### Basic authentication
@@ -7749,6 +8013,7 @@ Components are the React components the dashboard is built from, import them fro
 - [ColorSwatchPicker](https://v2.alineacms.com/docs/components/color-swatch-picker): Picks a color from a set of swatches.
 - [DropZone](https://v2.alineacms.com/docs/components/drop-zone): A target to drop files or other content on.
 - [Field](https://v2.alineacms.com/docs/components/field): The label, help text and error around your own input.
+- [Form](https://v2.alineacms.com/docs/components/form): Submits its fields and shows their validation errors.
 
 ### Collections
 - [Table](https://v2.alineacms.com/docs/components/table): Rows and columns with sorting, selection and dragging.
@@ -7782,6 +8047,7 @@ Components are the React components the dashboard is built from, import them fro
 - [FoldIcon](https://v2.alineacms.com/docs/components/fold-icon): A chevron that turns when its section opens.
 
 ### Layout
+- [Stack](https://v2.alineacms.com/docs/components/stack): Lays out its children in a row or column with a gap.
 - [Surface](https://v2.alineacms.com/docs/components/surface): A bordered panel for a group of content.
 - [Collapsible](https://v2.alineacms.com/docs/components/collapsible): A section that opens and closes.
 - [Page](https://v2.alineacms.com/docs/components/page): The header, content and footer of a dashboard page.
@@ -7826,7 +8092,7 @@ export function PriorityView({field}: FieldViewProps<PriorityField>) {
 }
 ```
 
-The components are styled by the dashboard's stylesheet and theme, so they are meant for code that runs inside the dashboard.
+The components are styled by the dashboard's stylesheet and theme. They are meant for code that runs inside the dashboard, but work on other pages too (see Theme tokens below).
 
 ## Conventions
 
@@ -7845,6 +8111,42 @@ The props of every component are typed, so your editor shows what each one accep
 
 Components with an `icon` prop take an icon component (any component that renders an `<svg>`, such as those from [react-icons](https://react-icons.github.io/react-icons) or copied from [Icones](https://icones.js.org)) or an element. The icons of the dashboard itself are exported from `alinea/dashboard/icons`.
 
+## Theme tokens
+
+The components are styled with CSS custom properties. `alinea/css` declares them, and its resets, only on elements with a `data-alinea-theme` attribute, so loading the stylesheet doesn't restyle the rest of a page. The dashboard sets the attribute on `<html>`, and popovers, dialogs and tooltips set it on themselves since they render outside the page. To use the components on a page of your site, import `alinea/css` and render them inside an element with `data-alinea-theme`. Add `data-theme="light"` or `data-theme="dark"` to that element to fix the color scheme, otherwise it follows the page.
+
+A theme only sets the inputs, as `light-dark()` pairs where a value differs per color scheme. Every other token is derived from them. Set them on the element with `data-alinea-theme`, for example `<div data-alinea-theme className="brand-theme">`:
+
+File: theme.css
+```css
+.brand-theme {
+  --alinea-radius: 6px;
+  --alinea-bg: light-dark(#ffffff, #18181b);
+  --alinea-fg: light-dark(#27272a, #e4e4e7);
+  --alinea-primary: light-dark(#2f6b45, #5fbf82);
+}
+```
+
+Popovers, dialogs and tooltips render outside that element and carry the attribute themselves, so a class on the page doesn't reach them: use `[data-alinea-theme]` as the selector to theme every part of the components on a page.
+
+Inputs:
+
+- `--alinea-font`, `--alinea-mono-font`, `--alinea-font-size-base` and `--alinea-radius`.
+- `--alinea-backdrop` (behind panels), `--alinea-bg` (panels), `--alinea-fg` (text) and `--alinea-border`.
+- `--alinea-primary`, `--alinea-danger`, `--alinea-warning` and `--alinea-success`, with `--alinea-primary-fg`, `--alinea-danger-fg` and `--alinea-warning-fg` for text on them.
+- `--alinea-ring`: the focus ring.
+- `--alinea-workspace-color`: the `color` option of the current workspace, set by the dashboard. It falls back to `--alinea-primary`.
+
+Derived tokens, to read in your own styles:
+
+- Text: `--alinea-fg-strong`, `--alinea-fg-muted`, `--alinea-fg-disabled` and `--alinea-field-label`.
+- Surfaces: `--alinea-bg-muted`, `--alinea-muted` (hover backgrounds), `--alinea-input`, `--alinea-overlay`, `--alinea-scrim` (behind dialogs) and `--alinea-border-strong`.
+- Tones: `--alinea-selected` and `--alinea-selected-fg`, and a `-subtle` background with a `-subtle-fg` text color for `primary`, `danger`, `warning` and `success`, eg. `--alinea-danger-subtle`.
+- Entry statuses: `--alinea-status-published`, `--alinea-status-draft` and `--alinea-status-unpublished`, each with a `-fg` color.
+- Shape and motion: `--alinea-radius-sm`, `--alinea-radius-lg`, `--alinea-radius-xl`, `--alinea-shadow-raised`, `--alinea-shadow-muted`, `--alinea-shadow-tooltip`, `--alinea-shadow-modal` and `--alinea-transition`.
+
+The color palette the default theme is built from (`--alinea-gray-500`, `--alinea-blue-800`, ...) is not part of this list and can change.
+
 ### Alert (https://v2.alineacms.com/docs/components/alert)
 A callout for an important message, with a title, a description and optional actions.
 
@@ -8669,44 +8971,133 @@ export function ComboBoxExample() {
 }
 ```
 
+## Groups and descriptions
+
+Group items under a label with ComboBoxGroup. Like SelectItem, a ComboBoxItem can show an `icon` and a `description` below its label. Values are strings or numbers: `onValueChange` receives the `value` of the picked item, typed like the `value` you pass.
+
+Example: ComboBox: groups
+```tsx
+import {ComboBox, ComboBoxGroup, ComboBoxItem} from 'alinea/components'
+import {
+  IcRoundDescription,
+  IcRoundFeed,
+  IcRoundImage
+} from 'alinea/dashboard/icons'
+
+export function ComboBoxGroupsExample() {
+  return (
+    <ComboBox label="Link to" style={{width: 280}}>
+      <ComboBoxGroup label="Pages">
+        <ComboBoxItem value="about" icon={IcRoundDescription}>
+          About us
+        </ComboBoxItem>
+        <ComboBoxItem
+          value="collection"
+          icon={IcRoundImage}
+          description="Products of the summer collection"
+        >
+          Summer collection
+        </ComboBoxItem>
+      </ComboBoxGroup>
+      <ComboBoxGroup label="Blog">
+        <ComboBoxItem
+          value="care"
+          icon={IcRoundFeed}
+          description="Published last week"
+        >
+          Caring for linen
+        </ComboBoxItem>
+      </ComboBoxGroup>
+    </ComboBox>
+  )
+}
+```
+
+## Load items as you type
+
+To search on a server, pass `filter={false}` so every item you render is shown, and `loading` while a request runs: it shows a spinner in the input, and in the list while it is empty. `useAsyncList` loads the items for the text in the input and cancels a request when a newer one replaces it. A function as `filter` replaces the default matching instead: `(textValue, inputValue) => boolean`.
+
+Example: ComboBox: async
+```tsx
+import {ComboBox, ComboBoxItem, useAsyncList} from 'alinea/components'
+
+const products = [
+  {id: 'shirt', title: 'Linen shirt'},
+  {id: 'chair', title: 'Oak dining chair'},
+  {id: 'throw', title: 'Wool throw'},
+  {id: 'table', title: 'Walnut side table'},
+  {id: 'lamp', title: 'Ceramic table lamp'}
+]
+
+// Stands in for a search request to your own API
+async function searchProducts(text: string) {
+  await new Promise(resolve => setTimeout(resolve, 400))
+  const query = text.toLowerCase()
+  return products.filter(product => product.title.toLowerCase().includes(query))
+}
+
+export function ComboBoxAsyncExample() {
+  const list = useAsyncList({
+    async load({filterText}) {
+      return {items: await searchProducts(filterText)}
+    }
+  })
+  return (
+    <ComboBox
+      label="Related product"
+      inputValue={list.filterText}
+      onInputValueChange={list.setFilterText}
+      filter={false}
+      loading={list.loading}
+      emptyMessage="No products found"
+      style={{width: 280}}
+    >
+      {list.items.map(product => (
+        <ComboBoxItem key={product.id} value={product.id}>
+          {product.title}
+        </ComboBoxItem>
+      ))}
+    </ComboBox>
+  )
+}
+```
+
 ## Props
 
 `ComboBox`
 A labelled text input that filters a list of options to pick from
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value | `string \| null` |  |  |
-| defaultValue | `string \| null` |  |  |
-| onValueChange | `(value: string \| null) => void` |  | Called with the selected value, or null when the selection is cleared |
+| value | `V \| null` |  | The value of the selected ComboBoxItem |
+| defaultValue | `V \| null` |  |  |
+| onValueChange | `(value: V \| null) => void` |  | Called with the selected value, or null when the selection is cleared |
 | inputValue | `string` |  |  |
 | defaultInputValue | `string` |  |  |
 | onInputValueChange | `(value: string) => void` |  |  |
 | placeholder | `string` |  |  |
 | allowsCustomValue | `boolean` |  | Keep text that does not match an item instead of reverting it on blur |
 | emptyMessage | `ReactNode` |  | Shown in the list when no item matches, the list stays closed if unset |
+| filter | `false \| ((textValue: string, inputValue: string) => boolean)` |  | Whether an item is shown for the typed text, defaults to a case and accent insensitive match anywhere in its text. Pass false to show every item, eg. when the server already filtered them. |
+| loading | `boolean` |  | Shows a spinner, eg. while the items for the typed text load |
 | name | `string` |  | Name of the hidden form input carrying the value |
 | autoFocus | `boolean` |  |  |
-| label | `ReactNode` |  |  |
-| description | `ReactNode` |  |  |
-| error | `ReactNode` |  |  |
-| required | `boolean` |  |  |
-| disabled | `boolean` |  |  |
-| readOnly | `boolean` |  |  |
-| icon | `IconType \| ReactElement` |  |  |
-| shared | `boolean` |  | Marks the field as shared between translations |
-| open | `boolean` |  |  |
-| defaultOpen | `boolean` |  |  |
-| onOpenChange | `(open: boolean) => void` |  |  |
-Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
 
 `ComboBoxItem`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value (required) | `string` |  |  |
+| value (required) | `Key` |  |  |
 | textValue | `string` |  | Text used for filtering and the input, defaults to string children |
 | disabled | `boolean` |  |  |
+| icon | `IconType \| ReactElement` |  | Icon shown before the label in the list |
+| description | `ReactNode` |  | Secondary text shown below the label in the list |
 Also accepts `className` and `style`.
 
+`ComboBoxGroup`
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| label | `ReactNode` |  |  |
+Also accepts `id` and `aria-*` labelling attributes.
+
 ### Command (https://v2.alineacms.com/docs/components/command)
 A searchable list of commands, like a command palette.
 
@@ -9030,7 +9421,7 @@ export function DateFieldExample() {
 `DateField`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| locale | `string; /** The date, `YYYY-MM-DD` */ value?: string \| null; defaultValue?: string \| null; onValueChange?: (value: string \| null) => void; /** The earliest valid date, `YYYY-MM-DD` */ min?: string; /** The latest valid date, `YYYY-MM-DD` */ max?: string; name?: string; autoFocus?: boolean;` |  | BCP 47 locale used to format dates, eg. `en-GB`, defaults to the user's locale |
+| locale | `string; /** The date, `YYYY-MM-DD` */ value?: string \| null; defaultValue?: string \| null; onValueChange?: (value: string \| null) => void; /** The earliest valid date, `YYYY-MM-DD` */ min?: string; /** The latest valid date, `YYYY-MM-DD` */ max?: string; /** * Name of the hidden form input, which submits the date like a native * date input: `YYYY-MM-DD`, or an empty string when no date is set */ name?: string; autoFocus?: boolean;` |  | BCP 47 locale used to format dates, eg. `en-GB`, defaults to the user's locale |
 | label | `ReactNode` |  |  |
 | description | `ReactNode` |  |  |
 | error | `ReactNode` |  |  |
@@ -9245,11 +9636,60 @@ export function DialogFormExample() {
 }
 ```
 
+## Submit a form
+
+Pass `onSubmit` to DialogContent to render its content as a [Form](https://v2.alineacms.com/docs/components/form): a Button with `type="submit"` submits it with the values of the named fields. The dialog closes once `onSubmit` resolves without errors. Errors it returns, keyed by field name, show on the fields and keep the dialog open. `onClose` on Dialog runs whenever the dialog closes, after `onOpenChange(false)`, for example to reset state. The form takes no room of its own (`display: contents`): put spacing such as a `gap` on DialogContent.
+
+Example: Dialog: submit
+```tsx
+import {
+  Button,
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+  TextField
+} from 'alinea/components'
+
+// Stands in for a request to your own API, which returns errors by field name
+async function movePage(data: FormData) {
+  await new Promise(resolve => setTimeout(resolve, 300))
+  if (data.get('path') === 'about') return {path: 'This path is taken'}
+  return undefined
+}
+
+export function DialogSubmitExample() {
+  return (
+    <Dialog>
+      <DialogTrigger variant="outline">Change path</DialogTrigger>
+      <DialogContent onSubmit={movePage}>
+        <DialogHeader>
+          <DialogTitle>Change path</DialogTitle>
+          <DialogDescription>Try “about” to see an error.</DialogDescription>
+        </DialogHeader>
+        <TextField label="Path" name="path" defaultValue="about" autoFocus />
+        <DialogFooter>
+          <DialogClose variant="ghost">Cancel</DialogClose>
+          <Button type="submit" color="primary">
+            Save
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+
 ## Props
 
 `Dialog`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
+| onClose | `() => void` |  | Called when the dialog closes, after `onOpenChange(false)` |
 | open | `boolean` |  |  |
 | defaultOpen | `boolean` |  |  |
 | onOpenChange | `(open: boolean) => void` |  |  |
@@ -9264,6 +9704,8 @@ Accepts every prop of `Button`.
 | size | `'default' \| 'lg' \| 'full'` | `'default'` | `default` fits its content up to a narrow width, `lg` is a fixed wide dialog and `full` fills the viewport (minus a margin), defaults to `default` |
 | dismissable | `boolean` | `true` | Close the dialog when clicking outside of it, defaults to true |
 | showCloseButton | `boolean` | `true` | Defaults to true |
+| onSubmit | `FormProps['onSubmit']` |  | Renders the content as a Form, submitted by a `type="submit"` Button. The dialog closes once this resolves without returning errors, which are shown on the fields otherwise. |
+| validationErrors | `ValidationErrors` |  | Errors keyed by field name, when the content is a form |
 Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
 
 `DialogHeader`
@@ -9774,13 +10216,80 @@ export function FoldIconExample() {
 | --- | --- | --- | --- |
 | expanded | `boolean` |  |  |
 
-### Heading (https://v2.alineacms.com/docs/components/heading)
-A title in one of five sizes.
+### Form (https://v2.alineacms.com/docs/components/form)
+A form whose fields show their validation errors. `onSubmit` receives the `FormData` of the named fields instead of the browser submitting the form. It can return errors keyed by field name, also from a promise, which show on those fields until they are edited.
 
-Example: Heading
+Example: Form
 ```tsx
-import {Heading} from 'alinea/components'
-
+import {
+  Button,
+  Form,
+  Select,
+  SelectItem,
+  Stack,
+  Text,
+  TextField
+} from 'alinea/components'
+import {useState} from 'react'
+
+// Stands in for a request to your own API, which returns errors by field name
+async function createPage(data: FormData) {
+  await new Promise(resolve => setTimeout(resolve, 300))
+  if (data.get('path') === 'about') return {path: 'This path is taken'}
+  return undefined
+}
+
+export function FormExample() {
+  const [created, setCreated] = useState<string>()
+  return (
+    <Form
+      style={{width: 300}}
+      onSubmit={async data => {
+        const errors = await createPage(data)
+        if (!errors) setCreated(String(data.get('title')))
+        return errors
+      }}
+    >
+      <Stack gap={16}>
+        <TextField label="Title" name="title" required />
+        <TextField label="Path" name="path" defaultValue="about" />
+        <Select label="Type" name="type" defaultValue="page">
+          <SelectItem value="page">Page</SelectItem>
+          <SelectItem value="post">Blog post</SelectItem>
+        </Select>
+        <Button type="submit" color="primary">
+          Create page
+        </Button>
+        {created && <Text size="sm">Created “{created}”</Text>}
+      </Stack>
+    </Form>
+  )
+}
+```
+
+## Validation
+
+Native constraints are checked when the form is submitted: `required`, and `pattern`, `minLength` and `maxLength` on a TextField. `validationErrors` shows errors you already have, for example from a server, keyed by field name like the ones `onSubmit` returns. An `error` set on a field itself takes precedence.
+
+The form controls of `alinea/components` take a `name` to be submitted under: text, number and select controls submit their value as a string, dates and times as ISO strings (`2026-09-23`, `14:30`) and MultipleSelect one entry per picked value. To submit a form from a dialog, pass `onSubmit` to [DialogContent](https://v2.alineacms.com/docs/components/dialog#submit-a-form): the dialog closes once it succeeds.
+
+## Props
+
+`Form`
+A form whose fields show validation errors: native constraints such as `required` once the form is submitted, and `validationErrors` or the errors returned by `onSubmit` by field name. An `error` set on a field itself takes precedence.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| validationErrors | `ValidationErrors` |  | Errors keyed by field name, eg. from the server. A field shows its error until it is edited. |
+| onSubmit | `(data: FormData) => FormSubmitResult \| Promise<FormSubmitResult>` |  | Called with the form data instead of submitting the form natively. Errors it returns are shown on the fields, next to `validationErrors`. |
+Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
+
+### Heading (https://v2.alineacms.com/docs/components/heading)
+A title in one of five sizes.
+
+Example: Heading
+```tsx
+import {Heading} from 'alinea/components'
+
 export function HeadingExample() {
   return (
     <div style={{display: 'grid', gap: 8, width: 360}}>
@@ -9899,6 +10408,10 @@ export function LinkExample() {
 }
 ```
 
+## Attributes
+
+Besides `href`, the link passes `target`, `rel`, `download`, `title`, `tabIndex`, `lang`, `hrefLang`, `referrerPolicy` and `aria-current` to its `<a>`. Mark the link to the page that is shown with `aria-current="page"`.
+
 ## Props
 
 `Link`
@@ -9908,6 +10421,12 @@ export function LinkExample() {
 | target | `string` |  |  |
 | rel | `string` |  |  |
 | download | `boolean \| string` |  |  |
+| title | `string` |  | Tooltip text |
+| tabIndex | `number` |  |  |
+| lang | `string` |  |  |
+| hrefLang | `string` |  |  |
+| referrerPolicy | `HTMLAttributeReferrerPolicy` |  |  |
+| aria-current | `boolean \| 'page' \| 'step' \| 'location' \| 'date' \| 'time'` |  |  |
 | variant | `'plain' \| 'underline'` | `'plain'` | `plain` underlines on hover, `underline` is always underlined |
 | disabled | `boolean` |  |  |
 | onClick | `(event: MouseEvent<HTMLAnchorElement>) => void` |  |  |
@@ -10084,35 +10603,27 @@ export function MultipleSelectExample() {
 }
 ```
 
+## Values
+
+The value is an array of the `value`s of the picked items, strings or numbers. With a `name` the field submits one form entry per value, like a native multiple select: read them with `formData.getAll(name)`.
+
 ## Props
 
 `MultipleSelect`
 A labelled field to pick several values from a searchable list, the selected values are shown as removable tags.
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value | `Array<string>` |  |  |
-| defaultValue | `Array<string>` |  |  |
-| onValueChange | `(value: Array<string>) => void` |  |  |
+| value | `Array<V>` |  | The values of the selected MultipleSelectItems |
+| defaultValue | `Array<V>` |  |  |
+| onValueChange | `(value: Array<V>) => void` |  |  |
 | placeholder | `string` |  |  |
 | emptyMessage | `ReactNode` | `'No options'` | Shown in the list when no item matches the search, defaults to "No options" |
-| name | `string` |  | Name of the hidden form input carrying the values |
-| label | `ReactNode` |  |  |
-| description | `ReactNode` |  |  |
-| error | `ReactNode` |  |  |
-| required | `boolean` |  |  |
-| disabled | `boolean` |  |  |
-| readOnly | `boolean` |  |  |
-| icon | `IconType \| ReactElement` |  |  |
-| shared | `boolean` |  | Marks the field as shared between translations |
-| open | `boolean` |  |  |
-| defaultOpen | `boolean` |  |  |
-| onOpenChange | `(open: boolean) => void` |  |  |
-Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
+| name | `string` |  | Name of the hidden form input carrying the values, it submits one entry per selected value like a native multiple select: read them with `formData.getAll(name)` |
 
 `MultipleSelectItem`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value (required) | `string` |  |  |
+| value (required) | `Key` |  |  |
 | textValue | `string` |  | Text used for searching and the tag, defaults to string children |
 | disabled | `boolean` |  |  |
 Also accepts `className` and `style`.
@@ -10216,6 +10727,10 @@ export function NumberFieldExample() {
 }
 ```
 
+## Formatting
+
+`formatOptions` takes the options of `Intl.NumberFormat`, such as a currency or a unit, and the number is shown and parsed in the locale of the dashboard. Digits are not grouped by default, since number fields often hold years or ids: pass `formatOptions={{useGrouping: true}}` to show `1,250` rather than `1250`. The value is a number, or `null` when the field is empty.
+
 ## Props
 
 `NumberField`
@@ -10227,7 +10742,7 @@ export function NumberFieldExample() {
 | min | `number` |  |  |
 | max | `number` |  |  |
 | step | `number` |  |  |
-| formatOptions | `Intl.NumberFormatOptions` |  |  |
+| formatOptions | `Intl.NumberFormatOptions` |  | How the number is shown and parsed. Digits are not grouped unless `useGrouping` is set: number fields often hold years and ids |
 | placeholder | `string` |  |  |
 | steppers | `boolean` | `true` | Show increment and decrement buttons, defaults to true |
 | name | `string` |  |  |
@@ -10641,7 +11156,7 @@ A text input for search queries with a clear button. The `icon` is shown inside
 Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
 
 ### Select (https://v2.alineacms.com/docs/components/select)
-Picks a single value from a list of options. The value is the `value` of the chosen SelectItem, and editors can clear it unless the field is required.
+Picks a single value from a list of options. The value is the `value` of the chosen SelectItem, and `onValueChange` receives it, typed like the `value` you pass: values are strings or numbers. Set `clearable` to show a button that clears the value again, `onValueChange` then receives `null`.
 
 Example: Select
 ```tsx
@@ -10704,7 +11219,7 @@ export function SelectGroupsExample() {
 
 ## States
 
-A placeholder shows while nothing is selected. Like the other form controls, a select takes `description`, `error`, `required`, `disabled` and `readOnly`.
+A placeholder shows while nothing is selected, and `clearable` adds a button to clear the selection. Like the other form controls, a select takes `description`, `error`, `required`, `disabled` and `readOnly`.
 
 Example: Select: states
 ```tsx
@@ -10713,7 +11228,7 @@ import {Select, SelectItem} from 'alinea/components'
 export function SelectStatesExample() {
   return (
     <div style={{display: 'grid', gap: 16, width: 280}}>
-      <Select label="Category" placeholder="Choose a category">
+      <Select label="Category" placeholder="Choose a category" clearable>
         <SelectItem value="bedroom">Bedroom</SelectItem>
         <SelectItem value="dining">Dining</SelectItem>
       </Select>
@@ -10733,33 +11248,22 @@ export function SelectStatesExample() {
 ## Props
 
 `Select`
-A labelled field to pick a single value from a list. The value can be cleared unless the field is required.
+A labelled field to pick a single value from a list. Set `clearable` to let the value be cleared again.
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value | `string \| null` |  |  |
-| defaultValue | `string \| null` |  |  |
-| onValueChange | `(value: string \| null) => void` |  | Called with the selected value, or null when the value is cleared |
+| value | `V \| null` |  | The value of the selected SelectItem |
+| defaultValue | `V \| null` |  |  |
+| onValueChange | `(value: V \| null) => void` |  | Called with the selected value, or null when the value is cleared |
 | placeholder | `string` |  |  |
+| clearable | `boolean` |  | Show a button that clears the value |
 | name | `string` |  | Name of the hidden form input carrying the value |
 | autoFocus | `boolean` |  |  |
 | size | `'default' \| 'sm'` | `'default'` | `sm` is as tall as a default Button, defaults to `default` |
-| label | `ReactNode` |  |  |
-| description | `ReactNode` |  |  |
-| error | `ReactNode` |  |  |
-| required | `boolean` |  |  |
-| disabled | `boolean` |  |  |
-| readOnly | `boolean` |  |  |
-| icon | `IconType \| ReactElement` |  |  |
-| shared | `boolean` |  | Marks the field as shared between translations |
-| open | `boolean` |  |  |
-| defaultOpen | `boolean` |  |  |
-| onOpenChange | `(open: boolean) => void` |  |  |
-Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
 
 `SelectItem`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value (required) | `string` |  |  |
+| value (required) | `Key` |  |  |
 | disabled | `boolean` |  |  |
 | icon | `IconType \| ReactElement` |  |  |
 | textValue | `string` |  | Text used for typeahead and the value, defaults to string children |
@@ -11021,6 +11525,48 @@ A circular progress indicator
 | value | `number` |  | Progress from 0 to 100, leave out for an indeterminate spinner |
 Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
 
+### Stack (https://v2.alineacms.com/docs/components/stack)
+Lays out its children in a column, or a row with `direction="row"`, with a `gap` between them: a number is in pixels, a string any CSS length. `align` positions the items across the stack (they stretch by default), `justify` along it, and `wrap` lets a row continue on the next line.
+
+Example: Stack
+```tsx
+import {Badge, Button, Stack, TextField} from 'alinea/components'
+
+export function StackExample() {
+  return (
+    <Stack gap={16} style={{width: 320}}>
+      <Stack direction="row" align="center" justify="between">
+        <strong>About us</strong>
+        <Badge status="draft">Draft</Badge>
+      </Stack>
+      <TextField label="Title" defaultValue="About us" />
+      <TextField label="Path" defaultValue="about" />
+      <Stack direction="row" gap={8} justify="end" wrap>
+        <Button variant="outline">Cancel</Button>
+        <Button color="primary">Save</Button>
+      </Stack>
+    </Stack>
+  )
+}
+```
+
+With `asChild` the stack lays out its single child element instead of rendering a div. `Stack` replaces the deprecated `HStack` and `VStack` of `alinea/ui`: `<Stack direction="row">` is an HStack.
+
+## Props
+
+`Stack`
+Lays out its children in a row or column with a gap between them
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| direction | `'row' \| 'column'` | `'column'` | Defaults to `column` |
+| gap | `number \| string` |  | Space between the items, a number is in pixels |
+| align | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` |  | Cross axis alignment of the items, they stretch by default |
+| justify | `'start' \| 'center' \| 'end' \| 'between'` |  | Main axis distribution of the items |
+| wrap | `boolean` |  | Wrap items onto multiple lines |
+| asChild | `boolean` |  | Lay out the single child element instead of rendering a div |
+| ref | `Ref<HTMLDivElement>` |  |  |
+Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
+
 ### Surface (https://v2.alineacms.com/docs/components/surface)
 A bordered panel for a group of content.
 
@@ -11240,6 +11786,84 @@ export function TableSelectionExample() {
 }
 ```
 
+## Load more rows
+
+`onLoadMore` is called when the rows are scrolled close to the end, to fetch the next page. While `loading` is set, a spinner shows below the rows, or in place of them while there are none. `useAsyncList` keeps the loaded pages: its `load` function receives the `cursor` the previous page returned, and `loadMore` does nothing once a page returns no cursor. Its `items`, `loading`, `loadMore`, `sortDescriptor` and `sort`, and `selectedKeys` and `setSelectedKeys` plug into the props of the table. `update(key, item)`, `remove(...keys)`, `prepend(...items)` and `append(...items)` change the loaded items without loading them again, for example after a dialog saves a row.
+
+Example: Table: async
+```tsx
+import {
+  Table,
+  TableCell,
+  TableRow,
+  TableTitle,
+  useAsyncList
+} from 'alinea/components'
+
+interface Product {
+  id: string
+  title: string
+  price: number
+}
+
+const materials = ['Linen', 'Oak', 'Wool', 'Walnut', 'Ceramic']
+const kinds = ['shirt', 'chair', 'throw', 'stool', 'lamp', 'table']
+
+// Stands in for a paged API: 20 products per page, 100 in total
+async function fetchProducts(page: number) {
+  await new Promise(resolve => setTimeout(resolve, 500))
+  const items: Array<Product> = Array.from({length: 20}, (_, i) => {
+    const n = page * 20 + i
+    const title = `${materials[n % 5]} ${kinds[n % 6]} ${n + 1}`
+    return {id: `product-${n}`, title, price: 40 + ((n * 37) % 300)}
+  })
+  return {items, cursor: page < 4 ? page + 1 : undefined}
+}
+
+export function TableAsyncExample() {
+  const list = useAsyncList<Product, number>({
+    load: ({cursor = 0}) => fetchProducts(cursor)
+  })
+  return (
+    <div style={{width: 420, height: 260}}>
+      <Table
+        aria-label="Products"
+        items={list.items}
+        columns={[
+          {id: 'title', header: 'Title', width: '1fr'},
+          {id: 'price', header: 'Price', width: 100, align: 'end'}
+        ]}
+        loading={list.loading}
+        onLoadMore={list.loadMore}
+      >
+        {product => (
+          <TableRow id={product.id} textValue={product.title}>
+            <TableTitle title={product.title} />
+            <TableCell align="end">€{product.price}</TableCell>
+          </TableRow>
+        )}
+      </Table>
+    </div>
+  )
+}
+```
+
+```tsx
+import {useAsyncList} from 'alinea/components'
+
+const list = useAsyncList({
+  async load({cursor, filterText, sort, signal}) {
+    const res = await fetch(`/api/products?page=${cursor ?? 1}`, {signal})
+    const {items, next} = await res.json()
+    // Leave out the cursor, or return null, on the last page
+    return {items, cursor: next}
+  }
+})
+// list.items, list.loading, list.hasMore, list.error,
+// list.loadMore(), list.reload(), list.setFilterText(text), list.sort(sort),
+// list.update(id, item), list.remove(id), list.prepend(item)
+```
+
 ## Props
 
 `Table`
@@ -11260,6 +11884,8 @@ export function TableSelectionExample() {
 | onSortChange | `(descriptor: SortDescriptor) => void` |  |  |
 | onRowAction | `(key: Key) => void` |  | Called when a row is activated (see `selectionBehavior`), rows can override it with their own `onAction` |
 | renderEmptyState | `() => ReactNode` |  |  |
+| loading | `boolean` |  | Shows a spinner in place of the rows while there are none, below the rows otherwise |
+| onLoadMore | `() => void` |  | Called when the rows are scrolled close to the end, to load the next page (see useAsyncList) |
 | dependencies | `ReadonlyArray<unknown>` |  | Rows are cached per item, list the values `children` reads besides the item to render them again when those change |
 | children (required) | `(item: T) => ReactElement` |  |  |
 
@@ -11302,6 +11928,9 @@ Also accepts `className` and `style`.
 | suffix | `ReactNode` |  | Shown right after the title, eg. a status icon |
 Also accepts `className` and `style`.
 
+`useAsyncList`
+Loads a list of items, with sorting, filtering and paging
+
 ## Accessibility
 
 Built on the React Aria grid: the arrow keys move between rows, Space selects a row and Enter runs its action. Sortable column headers announce their sort direction.
@@ -11570,7 +12199,7 @@ export function TextFieldStatesExample() {
 
 ## Multiline
 
-A multiline field starts at `rows` lines and grows as editors type.
+A multiline field starts at `rows` lines and grows as editors type, up to `maxRows` lines when you set it, then it scrolls.
 
 Example: TextField: multiline
 ```tsx
@@ -11582,6 +12211,7 @@ export function TextFieldMultilineExample() {
       label="Description"
       multiline
       rows={4}
+      maxRows={8}
       defaultValue="A relaxed shirt in washed linen that softens with every wear."
       style={{width: 300}}
     />
@@ -11622,6 +12252,10 @@ export function TextFieldIconsExample() {
 }
 ```
 
+## Native input attributes
+
+`type`, `name`, `autoComplete`, `inputMode`, `pattern`, `minLength` and `maxLength` are passed to the input. `inputMode` picks the virtual keyboard on touch devices, eg. `numeric` for a code, and `pattern` is a regular expression the value must match, checked when the field is in a [Form](https://v2.alineacms.com/docs/components/form).
+
 ## Props
 
 `TextField`
@@ -11634,6 +12268,7 @@ export function TextFieldIconsExample() {
 | type | `'text' \| 'email' \| 'url' \| 'password' \| 'tel' \| 'search'` | `'text'` |  |
 | multiline | `boolean` |  | Render a textarea that grows with its content |
 | rows | `number` | `1` | Minimum number of rows of a multiline field |
+| maxRows | `number` |  | Maximum number of rows a multiline field grows to before it scrolls |
 | startIcon | `IconType \| ReactElement` |  | Icon displayed inside the input, before the text |
 | endIcon | `IconType \| ReactElement` |  | Icon displayed inside the input, after the text |
 | name | `string` |  |  |
@@ -11641,6 +12276,8 @@ export function TextFieldIconsExample() {
 | autoComplete | `string` |  |  |
 | maxLength | `number` |  |  |
 | minLength | `number` |  |  |
+| inputMode | `'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search'` |  | Which virtual keyboard to show, eg. `numeric` for a code |
+| pattern | `string` |  | A regular expression the value must match to be valid |
 | onBlur | `(event: FocusEvent<TextFieldElement>) => void` |  |  |
 | onFocus | `(event: FocusEvent<TextFieldElement>) => void` |  |  |
 | onKeyDown | `(event: KeyboardEvent<TextFieldElement>) => void` |  |  |
@@ -11679,13 +12316,17 @@ export function TimeFieldExample() {
 }
 ```
 
+## Value
+
+The value is an ISO time string: `14:30`, or `14:30:15` with `granularity="second"`. With a `name` the field submits the same string in a form, like a native time input, and an empty string when no time is set. `hourCycle` only changes how the time is shown.
+
 ## Props
 
 `TimeField`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | locale | `string; /** The time, `HH:mm` or `HH:mm:ss` */ value?: string \| null; defaultValue?: string \| null; /** Receives `HH:mm`, or `HH:mm:ss` when granularity is `second` */ onValueChange?: (value: string \| null) => void; /** The earliest valid time, `HH:mm` or `HH:mm:ss` */ min?: string; /** The latest valid time, `HH:mm` or `HH:mm:ss` */ max?: string; /** The smallest unit that can be edited, defaults to `minute` */ granularity?: 'minute' \| 'second'; /** Defaults to the locale's hour cycle */ hourCycle?: 12 \| 24` |  | BCP 47 locale used to format dates, eg. `en-GB`, defaults to the user's locale |
-| name | `string` |  |  |
+| name | `string` |  | Name of the hidden form input, which submits the time like a native time input: `HH:mm`, or `HH:mm:ss` when granularity is `second`, and an empty string when no time is set |
 | autoFocus | `boolean` |  |  |
 | label | `ReactNode` |  |  |
 | description | `ReactNode` |  |  |
@@ -12095,7 +12736,28 @@ export function range(
 }
 ```
 
-`Field.Create<Value, Options>` is the type of a field that stores `Value` (anything JSON can hold) and accepts your `Options` next to the standard ones: `initialValue`, `required`, `readOnly`, `hidden`, `shared` and `validate`. Queries return the stored value as it is.
+`Field.Create<Value, Options>` is the type of a field that stores `Value` (anything JSON can hold) and accepts your `Options` next to the standard ones: `initialValue`, `required`, `readOnly`, `hidden`, `shared`, `validate` and `width`, the width of the field in the entry form. Queries return the stored value as it is.
+
+To describe the options as an interface, extend `FieldOptions` from `alinea/core` and type the options argument with `WithoutLabel`:
+
+File: fields/Rating.ts
+```tsx
+import {Field} from 'alinea'
+import type {FieldOptions, WithoutLabel} from 'alinea'
+
+export interface RatingOptions extends FieldOptions<number> {
+  max?: number
+}
+
+export type RatingField = Field.Create<number, RatingOptions>
+
+export function rating(
+  label: string,
+  options: WithoutLabel<RatingOptions> = {}
+): RatingField {
+  return Field.create({label, options, view: '@/fields/Rating.view'})
+}
+```
 
 `Field.create` takes:
 
@@ -12221,9 +12883,13 @@ export function priority(
 }
 ```
 
+The entry editor sets `--alinea-header-height` to the height of its header. A view that fills the visible editor can size itself with it, for example `height: calc(100dvh - var(--alinea-header-height))`.
+
+Style your own markup with the [theme tokens](https://v2.alineacms.com/docs/components#theme-tokens), such as `--alinea-fg-muted`, `--alinea-border` and `--alinea-radius`, so it follows light and dark mode. `--alinea-workspace-color` holds the `color` of the current workspace.
+
 ## The alinea/cms API
 
-Everything in `alinea/cms` works in field views and in the other components the dashboard renders: `Field.view` sections and custom type and root views.
+Everything in `alinea/cms` works in field views and in the other components the dashboard renders for an entry: `Field.view` sections, entry `actions` and a type's `view`. A root's `view` is not part of an entry: the hooks that read the dashboard, such as `useGraph`, `useNavigate`, `useLocale` and `useUser`, and `EntryTable` work there, the field hooks, `EditField` and `EditFields` don't, and `useEntry()` returns `null`.
 
 Field hooks, for the field passed to a view or another field of the same entry, list row or object:
 
@@ -12232,24 +12898,55 @@ Field hooks, for the field passed to a view or another field of the same entry,
 - `useFieldOptions(field)`: the field's options, including `label` and the resolved `readOnly` and `hidden`.
 - `useFieldError(field)`: the validation message from `required` or `validate`, if any.
 - `useFieldKey(field)`: the key the field is stored under, such as `'title'`.
-- `useSiblingFieldValue(key)`: the value of another field in the same entry, list row or object, by its key.
+- Other fields: pass any field of the same list row or object, of a parent row or of the entry to these hooks, it resolves in the nearest scope that holds it. Import the type from your schema (`useFieldValue(BlogPost.title)`) or pass the field through your field's options. A view shared by types that each define their own field passes its key instead: `useFieldValue('path')` reads that field of the same row, untyped. `useSiblingFieldValue(key)` is deprecated.
+
+A field in the rows of a list can read a field of the entry, here to suggest the post title as a caption:
+
+File: fields/Caption.view.tsx
+```tsx
+import {
+  type FieldViewProps,
+  useField,
+  useFieldOptions,
+  useFieldValue
+} from 'alinea/cms'
+import {TextField} from 'alinea/components'
+import {BlogPost} from '@/schema'
+import type {CaptionField} from './Caption'
+
+export function CaptionView({field}: FieldViewProps<CaptionField>) {
+  const [value, setValue] = useField(field)
+  const {label} = useFieldOptions(field)
+  // A field of the entry, read from inside a list row
+  const title = useFieldValue(BlogPost.title)
+  return (
+    <TextField
+      label={label}
+      value={value}
+      placeholder={title}
+      onValueChange={setValue}
+    />
+  )
+}
+```
 
 Entry and dashboard hooks:
 
-- `useEntry()`: the entry being edited, with its `id`, `title`, `url`, `workspace`, `root`, `locale`, `status` and the stored `data`. `null` outside an entry.
+- `useEntry()`: the entry being edited, with its `id`, `type`, `title`, `path`, `url`, `locale`, `status`, `workspace`, `root`, `parentId` and `data`. `data` holds the field values as saved, read the live value of a field while it is edited with `useFieldValue(field)`. `null` outside an entry.
 - `useLocale()`: the locale being edited, or `null` for content without translations.
 - `useGraph()`: query content from the dashboard with the same API as `cms`, for example to list entries in a picker.
 - `useUser()`, `usePolicy()`: the signed-in user and their [permissions](https://v2.alineacms.com/docs/roles-permissions).
-- `useNavigate()`: returns a function that opens an entry or root in the dashboard: `navigate({workspace, root, entryId})`. The editor is asked to confirm first when there are unsaved changes.
+- `useNavigate()`: returns a function that opens an entry or root in the dashboard: `navigate({entryId, locale})` looks up the entry's workspace and root, `navigate({workspace, root})` opens a root. Pass `view: 'edit'` or `view: 'overview'` to pick the form or the list of children. The editor is asked to confirm first when there are unsaved changes.
+- `href(location)` from `alinea`: the href of the same locations, for a link that also opens in a new tab: `<a href={href({entryId: post.id})}>`. It is a plain function, so it also works in table rows, in the `help` of a field and on the server, where you prefix the dashboard's url: `${baseUrl}/admin${href({entryId})}`.
 - `usePreviewMetadata()`: the title, description and other metadata the live preview reports for the current page.
 
 Components and types:
 
 - `FieldChrome`: the label, help text and error of a field around your own control.
-- `EditField`, `EditFields`: render a field, or a record of fields, with the view it is configured with, for example to lay out existing fields in a `Field.view` section.
+- `EditField`, `EditFields`: render a field, or a record of fields, with the view it is configured with, for example to lay out existing fields in a `Field.view` section. Pass an object field to `EditFields` to render its fields, or some of them, in the scope of the object: `<EditFields field={Product.dimensions} fields={{width: Product.dimensions.width}} />`.
 - `EntryTable`: a table of entries with the columns of an [overview](https://v2.alineacms.com/docs/overviews#entry-tables-in-your-own-views), for example to list related entries in a `Field.view` section.
 - `FieldViewProps<F>`, `SectionViewProps`, `TypeViewProps`, `RootViewProps`: the props the dashboard passes to a field view, a `Field.view` component, a type's `view` and a root's `view`.
-- `OverviewCellProps`, `OverviewActionProps`, `OverviewEntry`: the props of an overview column's `view` and of an overview action, and the entry they receive.
+- `OverviewCellProps`, `OverviewActionProps`, `OverviewEntry`: the props of an overview column's `view` and of an overview action, and the entry they receive. `EntryActionProps` and `DashboardEntry`: the props of an entry action and the entry `useEntry()` returns.
 
 ## Show a component between fields
 
@@ -12285,6 +12982,77 @@ export function ProductUrls() {
 }
 ```
 
+## Replace the form of a type
+
+A type's `view` replaces the form of its entries with your own component, for example to edit the fields in a layout of your own. The entry header stays above it, with the title, the status, the publish and draft buttons, the type's `actions` and the sidebar with history and references. The view fills the rest of the editor, without padding.
+
+File: schema/Product.ts
+```tsx
+import {Config, Field} from 'alinea'
+
+export const Product = Config.document('Product', {
+  view: '@/views/ProductView.view#ProductView',
+  fields: {
+    summary: Field.text('Summary', {multiline: true}),
+    price: Field.number('Price')
+  }
+})
+```
+
+File: views/ProductView.view.tsx
+```tsx
+import {EditField, useField} from 'alinea/cms'
+import {TextField} from 'alinea/components'
+import {Product} from '@/schema/Product'
+
+export function ProductView() {
+  const [summary = '', setSummary] = useField(Product.summary)
+  return (
+    <div style={{display: 'grid', gap: 16, padding: 24}}>
+      <TextField
+        label="Summary"
+        multiline
+        value={summary}
+        onValueChange={setSummary}
+      />
+      <EditField field={Product.price} />
+    </div>
+  )
+}
+```
+
+The view receives `TypeViewProps`: the `type` of the entry. It edits the entry like the form does: the field hooks, `EditField` and `EditFields` read and write the fields of the entry, the changes show up as unsaved edits in the header and are kept until the editor publishes or saves a draft, and leaving the entry with unsaved changes asks to confirm first. To fill the editor, size the view with `height: 100%`.
+
+## Add actions to the entry header
+
+Buttons that act on the entry, such as an export or a button that creates a related entry, go in the `actions` of its type. They render in the entry header next to the publish button and receive `EntryActionProps`: the `entry` and the `locale` it is edited in. The hooks of `alinea/cms` read and write its fields.
+
+File: schema/Product.ts
+```tsx
+import {Config, Field} from 'alinea'
+
+export const Product = Config.document('Product', {
+  fields: {title: Field.text('Title')},
+  actions: ['@/views/ExportProduct.view#ExportProduct']
+})
+```
+
+File: views/ExportProduct.view.tsx
+```tsx
+import {type EntryActionProps, useFieldValue} from 'alinea/cms'
+import {Button} from 'alinea/components'
+import {Product} from '@/schema/Product'
+
+export function ExportProduct({entry}: EntryActionProps) {
+  const title = useFieldValue(Product.title)
+  return (
+    <Button onClick={() => window.open(`/api/export/${entry.id}`)}>
+      Export {title}
+    </Button>
+  )
+}
+```
+
 ## Upgrading from Alinea 1.x
 
 Field views from 1.x keep working, with deprecated APIs:
@@ -12292,6 +13060,7 @@ Field views from 1.x keep working, with deprecated APIs:
 - `useField` from `alinea/dashboard` returns `{value, mutator, options, label, error}`. Replace it with the tuple `useField` from `alinea/cms` and the separate `useFieldOptions` and `useFieldError`. `useFieldValue`, `useFieldOptions`, `useFieldError` and `useFieldKey` also move to `alinea/cms`, and `useFieldMutator` becomes `useFieldSetter`.
 - `InputLabel` from `alinea/dashboard` is now the `Field` component. It no longer shows `help` from `{...options}`: use `FieldChrome` from `alinea/cms`, which reads it from the field, or pass the help text to `Field` from `alinea/components` as `description`.
 - `useLocale`, `useGraph` and `useEntryEditor` from `alinea/dashboard/hook/*` become `useLocale`, `useGraph` and `useEntry` from `alinea/cms`.
+- `useEntryEditor` still works as a shim for views that only read the entry: `activeVersion` has the `id`, `locale`, `path`, `status`, `title` and `type` of the entry, and `activeVersion.data` only has `path`. Reading another field of it throws, read field values with `useFieldValue(field)` instead. `useEntry()` returns the same entry as a `DashboardEntry`, with its saved field values in `data`.
 - Hooks imported from `alinea/dashboard/hooks` still work, but that module is internal: import them from `alinea/cms`.
 - Components from `alinea/ui` were removed. Use [`alinea/components`](https://v2.alineacms.com/docs/components).
 
@@ -12362,16 +13131,18 @@ export const products = Config.root('Products', {
 - `sort`: the default order of the children, in the overview and in the sidebar tree. See [Sorting](#sorting).
 - `sorts`: the orders editors can pick in the filter and sort menu, keyed by name. See [Sort options](#sort-options).
 - `filters`: filters editors can apply in the filter and sort menu, keyed by name. See [Filters](#filters).
+- `tabs`: tabs above the listed entries, keyed by a name kept in the url. See [Tabs](#tabs).
 - `layout`: `'table'` or `'cards'`, the layout the overview opens in. Editors can still switch.
 - `thumbnail`: the image shown on cards: an image field, or one per type (`{BlogPost: BlogPost.cover, Event: Event.poster}`). Defaults to the first image found in the fields of the entry.
 - `actions`: components rendered in the toolbar of the overview, such as an export button. See [Actions](#actions).
+- `header`: a component rendered between the toolbar and the listed entries, such as totals. See [Header](#header).
 
 ## Columns
 
 `Config.column(options)` takes:
 
 - `header` (required): the column header.
-- `select`: what the column shows. Anything a [query](https://v2.alineacms.com/docs/query) can select: a field (`Product.price`), an expression (`Query.url`), a query of linked entries, or an object of those.
+- `select`: what the column shows. Anything a [query](https://v2.alineacms.com/docs/query) can select: a field (`Product.price`), an expression (`Query.url`), a query of linked entries, a relation such as `Query.referencedBy`, or an object of those.
 - `format`: a function that turns the selected value into text: `(value, {locale}) => string`.
 - `view`: a React component that renders the cell, see [Custom cells](#custom-cells).
 - `sortBy`, `sortable`: how the column sorts, see [Sorting](#sorting).
@@ -12484,7 +13255,34 @@ Force them on or off with `builtins`, for example `{type: true}` to always show
 
 ## Sorting
 
-Editors sort an overview by clicking a column header, or from the filter and sort menu. The title, the built-in columns, expressions of the entry (such as `Query.title`) and fields that hold a single value (text, number, date, select, check, path, ...) are sortable. Columns that select links, lists, multiple selects, rich text or JSON need `sortBy`: an expression, or a query of a linked entry that selects a single expression, such as `Product.brand.first({select: Query.title})`. Set `sortable: false` to turn sorting off for a column.
+Editors sort an overview by clicking a column header, or from the filter and sort menu. The title, the built-in columns, expressions of the entry (such as `Query.title`) and fields that hold a single value (text, number, date, select, check, path, ...) are sortable, and so are columns that count related entries, such as `Query.referencedBy({type: Product, count: true})`. Columns that select links, lists, multiple selects, rich text or JSON need `sortBy`: an expression, or a query of a linked entry that selects a single expression, such as `Product.brand.first({select: Query.title})`. Set `sortable: false` to turn sorting off for a column.
+
+A column that counts the products of each brand, which editors can sort by:
+
+File: schema/Brands.ts
+```tsx
+import {Config, Query} from 'alinea'
+import {Product} from './Product'
+
+export const Brands = Config.document('Brands', {
+  contains: ['Brand'],
+  fields: {},
+  overview: {
+    columns: {
+      products: Config.column({
+        header: 'Products',
+        width: 100,
+        align: 'end',
+        select: Query.referencedBy({
+          type: Product,
+          field: Product.brand,
+          count: true
+        })
+      })
+    }
+  }
+})
+```
 
 Sorting runs in the database query, and entries without a value come last. It only changes what the editor sees, never the stored order of the entries. While a list is sorted, "Sorted by Price · Reset" shows in the toolbar and rows can't be reordered; Reset goes back to the default order. The sort is kept in the url (`?sort=price`, or `?sort=-price` for descending), so it survives a reload and can be shared, and it is restored when the editor comes back to the overview in the same session. Search results stay ordered by relevance.
 
@@ -12555,6 +13353,74 @@ export const Products = Config.document('Products', {
 })
 ```
 
+### Options from the content
+
+`options` can also be a function that loads them, for example an option per category entry. It receives the `graph` to query and the `locale` of the overview, and runs when the overview opens. Filters can match on the entries that link to a listed entry too, with `_referenced` (see [Entries that link here](https://v2.alineacms.com/docs/query/related#entries-that-link-here)):
+
+File: schema/Products.ts
+```tsx
+import {Config, Query} from 'alinea'
+import {Category, Product} from './Product'
+
+export const Products = Config.document('Products', {
+  contains: ['Product'],
+  overview: {
+    filters: {
+      category: {
+        label: 'Category',
+        multiple: true,
+        async options({graph, locale}) {
+          const categories = await graph.find({
+            type: Category,
+            locale,
+            select: {id: Query.id, title: Query.title},
+            orderBy: {asc: Query.title}
+          })
+          return Object.fromEntries(
+            categories.map(category => [
+              category.id,
+              {
+                label: category.title,
+                filter: {categories: {includes: {_entry: category.id}}}
+              }
+            ])
+          )
+        }
+      },
+      usage: {
+        label: 'Usage',
+        options: {
+          linked: {label: 'Linked from other entries', filter: {_referenced: true}},
+          unused: {label: 'Not linked anywhere', filter: {_referenced: false}}
+        }
+      }
+    }
+  },
+  fields: {}
+})
+```
+
+## Tabs
+
+`tabs` shows tabs above the listed entries, apart from the filter and sort menu. Each tab has a `label` and an optional `filter`, like the options of a filter. A tab without a filter lists every child. The first tab is selected when the overview opens. The key of the selected tab is kept in the url (`?tab=active`) and the overview remembers it when the editor returns to it. Entries match the filter of the tab, the applied filters and the search terms.
+
+File: schema/Products.ts
+```tsx
+import {Config} from 'alinea'
+
+export const Products = Config.document('Products', {
+  contains: ['Product'],
+  overview: {
+    tabs: {
+      all: {label: 'All'},
+      active: {label: 'Active', filter: {status: 'active'}},
+      archived: {label: 'Archived', filter: {status: 'archived'}}
+    }
+  },
+  fields: {}
+})
+```
+
 ## Mixed lists
 
 When a parent contains several types, a column can select a different value per type. Key `select` and `sortBy` by the type names of your schema:
@@ -12640,6 +13506,33 @@ export function ExportProducts({query}: OverviewActionProps) {
 }
 ```
 
+## Header
+
+`header` renders a component between the toolbar (and the tabs) and the listed entries, for example totals or a chart of what is listed. It receives `OverviewHeaderProps`: the `workspace`, `root` and `parentId` of the list, the `locale`, the `search` terms, the `filter` of the selected tab and the applied filters (undefined when none applies) and a `query` for the listed entries, without paging. Like `actions`, it takes a component or a path to one: `header: '@/views/ProductTotals'`.
+
+File: views/ProductTotals.tsx
+```tsx
+import {type OverviewHeaderProps, useGraph} from 'alinea/cms'
+import {Stack, Text} from 'alinea/components'
+import {useEffect, useState} from 'react'
+import {Product} from '@/schema/Product'
+
+export function ProductTotals({query}: OverviewHeaderProps) {
+  const graph = useGraph()
+  const [prices, setPrices] = useState<Array<number | null>>([])
+  useEffect(() => {
+    graph.find({...query, select: Product.price}).then(setPrices)
+  }, [graph, query])
+  const total = prices.reduce<number>((sum, price) => sum + (price ?? 0), 0)
+  return (
+    <Stack direction="row" gap={24}>
+      <Text>{prices.length} products</Text>
+      <Text>€{total} in total</Text>
+    </Stack>
+  )
+}
+```
+
 ## Entry tables in your own views
 
 `EntryTable` from `alinea/cms` renders a table of entries with the columns of an overview: the headers sort and a row opens its entry. Use it in a `Field.view` section, or any other custom view, to show related entries. Here a brand lists its products:
@@ -12682,7 +13575,7 @@ export function BrandProducts() {
 `EntryTable` takes:
 
 - `type`: list entries of this type, or of an array of types.
-- `filter`: a query [filter](https://v2.alineacms.com/docs/query/filtering), such as `{brand: {has: {_entry: entry.id}}}`.
+- `filter`: a query [filter](https://v2.alineacms.com/docs/query/filtering), such as `{brand: {has: {_entry: entry.id}}}`. Conditions on related entries work too: `{_referenced: Query.referencedBy({type: Product, filter: {stock: {gt: 0}}})}` lists the entries that a product in stock links to.
 - `workspace`, `root`, `parentId`: only list entries in this workspace or root, or the children of this entry (`null` for the top level).
 - `overview`: the columns and default order to use: an overview object, or the type or root that configures one. Defaults to the overview of the root or type that contains `type`.
 - `columns`: show these columns instead of those of the overview.
@@ -12743,7 +13636,7 @@ Prefer this over a type with a hidden title and a single `Field.view`: that crea
 
 Two other options replace parts of the dashboard:
 
-- A type's `view` replaces the editor of entries of that type. It receives `TypeViewProps`: `{type}`.
+- A type's `view` replaces the form of entries of that type, below the entry header. It receives `TypeViewProps`: `{type}`.
 - A type's `defaultView: 'overview'` opens the overview of an entry's children first, instead of its form.
 
 ## Upgrading from Alinea 1.x
@@ -12812,9 +13705,11 @@ The URL of the API route that serves the dashboard and media files: the route th
 
 The URL of your website, either one string or one per environment: `{development, production}`, picked by `NODE_ENV`. A value without a protocol gets `https://`.
 
-- `alinea build` exits with `No baseUrl was set for the production build` when there is no production URL.
+- It is required for production builds when `handlerUrl` is relative: `alinea build` exits, and queries on your site throw, with `Missing baseUrl in Alinea config: set baseUrl.production to the url of your site, …`. An absolute `handlerUrl` doesn't need it.
 - In production your site reaches the handler at `handlerUrl` resolved against this URL, to check for new content. That includes `next start` on your machine, which talks to the production URL.
 
+Server renders have no request to take the origin from (static pages and pages from `generateStaticParams` are rendered without one, and reading the request headers would make every route dynamic), so Alinea doesn't guess it. Set `baseUrl.production`, or make `handlerUrl` absolute.
+
 Most projects read the production URL from an environment variable, see [Environment variables](#environment-variables) below.
 
 ## Dashboard options
@@ -13016,9 +13911,11 @@ Options
   --fix           Any missing or incorrect properties will be overwritten by their default
 ```
 
-`--config` and `--dir` work as for `alinea dev`. `--fix` rewrites content files whose data doesn't match the schema, filling missing or invalid properties with their defaults, and exits without running the command after `--`. Commit the result.
+`--config` and `--dir` work as for `alinea dev`. `--fix` rewrites content files whose data doesn't match the schema, filling missing or invalid properties with their defaults, and points media files whose `location` is a url at the file of the same name in the `mediaDir`. It exits without running the command after `--`. Commit the result.
+
+The build stops with an error when the config can't be loaded, when `handlerUrl` is missing or when `baseUrl` has no production URL while `handlerUrl` is relative, see [Configuration](https://v2.alineacms.com/docs/configuration).
 
-The build stops with an error when the config can't be loaded, when `handlerUrl` is missing or when `baseUrl` has no production URL, see [Configuration](https://v2.alineacms.com/docs/configuration).
+`alinea dev` and `alinea build` warn about media files whose `location` is a url, which can't be served (some 1.x saves wrote the upload url there). The warning names the file and, when the `mediaDir` holds a file of the same name, suggests `alinea build --fix` to point the location at it.
 
 ## Deploying