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

package/docs/overviews.md

@@ -64,16 +64,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](query.md) 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](query.md) 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).
@@ -186,7 +188,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.
 
@@ -257,6 +286,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](query/related.md#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:
@@ -342,6 +439,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:
@@ -384,7 +508,7 @@ export function BrandProducts() {
 `EntryTable` takes:
 
 - `type`: list entries of this type, or of an array of types.
-- `filter`: a query [filter](query/filtering.md), such as `{brand: {has: {_entry: entry.id}}}`.
+- `filter`: a query [filter](query/filtering.md), 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.
@@ -445,7 +569,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

package/docs/query/filtering.md

@@ -21,6 +21,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](related.md#entries-that-link-here).
 
 Every key has to match, so several keys in one filter mean "and".
 
@@ -152,6 +153,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](../fields/text.md) and [rich text](../fields/rich-text.md) fields support it, also inside lists, objects and rich text blocks.

package/docs/query/related.md

@@ -1,6 +1,6 @@
 # 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'
@@ -100,9 +100,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'
@@ -110,19 +110,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}
 }
 ```
 

package/docs/query.md

@@ -79,7 +79,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](query/related.md) and `Query.snippet` for [search results](query/filtering.md).
+`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](query/related.md) and `Query.snippet` for [search results](query/filtering.md).
+
+### 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](fields/object.md) 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>>`.
 

package/docs/quickstart.md

@@ -20,22 +20,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
@@ -44,7 +44,7 @@ Alinea requires a [config file](configuration.md) which can be auto-generated by
 
 Variant: npm
 ```shellscript
-npx alinea@preview init
+npx alinea@rc init
 ```
 
 Variant: yarn

package/docs/schema/document.md

@@ -57,6 +57,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:

package/docs/schema/type.md

@@ -19,6 +19,7 @@ The label ("Author") is what editors see. The name the type is stored under is i
 ## Options
 
 - `fields` (required): the [fields](../fields.md) of the type, keyed by name. Field names must start with a letter and contain only letters, digits and underscores. Spread [tabs](../fields/tabs.md) 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](../overviews.md).
 - `insertOrder`: where new children are added: `'first'`, `'last'` or `'free'` (default), which lets the editor choose in the create dialog.
@@ -27,7 +28,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](../live-previews.md) 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](../custom-fields.md#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](../custom-fields.md#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.
 

package/docs/upgrading.md

@@ -4,23 +4,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
 
@@ -50,6 +52,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](configuration.md) for the new `maxUploadSize` and `tracer` options.
@@ -70,6 +89,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.
 
@@ -123,6 +164,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](fields/rich-text.md#custom-attributes).
+
 ### Edit.move
 
 ```tsx
@@ -157,9 +200,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')
   }
 })
 
@@ -167,7 +213,7 @@ export const GET = handler
 export const POST = handler
 ```
 
-Errors thrown in `afterCommit` are logged and don't fail the commit. See [Instant publishing](instant-publishing.md).
+`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](instant-publishing.md).
 
 ### remote is replaced by backend
 
@@ -203,7 +249,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
@@ -215,6 +261,23 @@ import {Button, Spinner} from 'alinea/components'
 
 See [Components](components.md). 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](components.md#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:
@@ -231,11 +294,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](custom-fields.md) 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](custom-fields.md) 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
 
@@ -282,6 +345,24 @@ See [Overviews](overviews.md) for sorting, custom cells and toolbar actions.
 
 `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](internationalization.md) for per-field translations, URL aliases and backlinks, [instant publishing](instant-publishing.md) and the [MCP server](mcp.md) for coding agents.