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

package/docs/components.md

@@ -34,6 +34,7 @@ Components are the React components the dashboard is built from, import them fro
 - [ColorSwatchPicker](components/color-swatch-picker.md): Picks a color from a set of swatches.
 - [DropZone](components/drop-zone.md): A target to drop files or other content on.
 - [Field](components/field.md): The label, help text and error around your own input.
+- [Form](components/form.md): Submits its fields and shows their validation errors.
 
 ### Collections
 - [Table](components/table.md): Rows and columns with sorting, selection and dragging.
@@ -67,6 +68,7 @@ Components are the React components the dashboard is built from, import them fro
 - [FoldIcon](components/fold-icon.md): A chevron that turns when its section opens.
 
 ### Layout
+- [Stack](components/stack.md): Lays out its children in a row or column with a gap.
 - [Surface](components/surface.md): A bordered panel for a group of content.
 - [Collapsible](components/collapsible.md): A section that opens and closes.
 - [Page](components/page.md): The header, content and footer of a dashboard page.
@@ -111,7 +113,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
 
@@ -129,3 +131,39 @@ The props of every component are typed, so your editor shows what each one accep
 ## Icons
 
 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.

package/docs/configuration.md

@@ -56,9 +56,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

package/docs/custom-fields.md

@@ -28,7 +28,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:
 
@@ -154,9 +175,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](components.md#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:
 
@@ -165,24 +190,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](roles-permissions.md).
-- `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](overviews.md#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
 
@@ -218,6 +274,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:
@@ -225,6 +352,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`](components.md).
 

package/docs/deploy/self-host.md

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

package/docs/deploy.md

@@ -78,7 +78,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
@@ -92,9 +92,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')
   }
 })
 

package/docs/fields/image.md

@@ -36,7 +36,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](../workspaces/media.md).
 - `focus`: the focal point as `{x, y}`, each between 0 and 1. Use it as `object-position` when you crop the image.

package/docs/fields/list.md

@@ -73,6 +73,25 @@ export default Config.type("List field", {
 
 Row types are ordinary [Types](../schema/type.md): 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:

package/docs/fields/object.md

@@ -41,11 +41,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: {
@@ -61,8 +61,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

package/docs/fields/rich-text.md

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

package/docs/index.md

@@ -45,7 +45,7 @@ The documentation of this version of Alinea, one Markdown file per page of https
 - [Querying content](query.md): Read content with the methods on your CMS instance.
   - [Structural](query/structural.md): Most queries start by saying which entries you want: of a type, at a url, in a root, in a locale. Then you choose what to get back and in which order.
   - [Filtering](query/filtering.md): Use filter to match entries on the values of their fields, and search to find entries by the words they contain.
-  - [Related](query/related.md): 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.
+  - [Related](query/related.md): 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…
   - [Advanced](query/advanced.md): Patterns for larger sites: nesting relations, querying several types at once, reusing parts of queries and controlling how fresh the content is.
   - [Examples](query/examples.md): Complete queries for pages most sites have. They use the example schema and the Next.js App Router, and assume a pages root without i18n unless noted.
 
@@ -80,7 +80,7 @@ The documentation of this version of Alinea, one Markdown file per page of https
   - [Code](components/code.md)
   - [Collapsible](components/collapsible.md)
   - [ColorSwatchPicker](components/color-swatch-picker.md)
-  - [ComboBox](components/combo-box.md)
+  - [ComboBox](components/combo-box.md): Group items under a label with ComboBoxGroup. Like SelectItem, a ComboBoxItem can show an icon and a description below its label.
   - [Command](components/command.md): A searchable list of commands, like a command palette.
   - [ContentCard](components/content-card.md)
   - [ContentGrid](components/content-grid.md): A selectable grid of cards, like the media library.
@@ -95,13 +95,14 @@ The documentation of this version of Alinea, one Markdown file per page of https
   - [Field](components/field.md): The label, help text and error around your own input.
   - [FileTrigger](components/file-trigger.md)
   - [FoldIcon](components/fold-icon.md)
+  - [Form](components/form.md): A form whose fields show their validation errors. onSubmit receives the FormData of the named fields instead of the browser submitting the form.
   - [Heading](components/heading.md)
   - [Icon](components/icon.md)
   - [Kbd](components/kbd.md)
-  - [Link](components/link.md)
+  - [Link](components/link.md): Besides href, the link passes target, rel, download, title, tabIndex, lang, hrefLang, referrerPolicy and aria-current to its <a>.
   - [List](components/list.md)
   - [MediaPreview](components/media-preview.md): A thumbnail of an image or an icon for other files.
-  - [MultipleSelect](components/multiple-select.md)
+  - [MultipleSelect](components/multiple-select.md): The value is an array of the values of the picked items, strings or numbers.
   - [NavRail](components/nav-rail.md)
   - [NumberField](components/number-field.md): A number input with increment and decrement buttons.
   - [Page](components/page.md): The header, content and footer of a dashboard page.
@@ -110,10 +111,11 @@ The documentation of this version of Alinea, one Markdown file per page of https
   - [RadioGroup](components/radio-group.md)
   - [ResizablePanelGroup](components/resizable-panel-group.md)
   - [SearchField](components/search-field.md): A text input for search queries, with a clear button.
-  - [Select](components/select.md): 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.
+  - [Select](components/select.md): 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:…
   - [Sidebar](components/sidebar.md)
   - [SortableList](components/sortable-list.md): Rows that editors reorder by dragging, like list fields.
   - [Spinner](components/spinner.md)
+  - [Stack](components/stack.md): 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.
   - [Surface](components/surface.md)
   - [Switch](components/switch.md): Turns a setting on or off, with an immediate effect. For choices that are saved later, as part of a form, use a Checkbox.
   - [Table](components/table.md): Rows and columns of data with sorting, selection, nested rows and drag and drop. Describe the columns up front, then render a TableRow for every item.
@@ -121,7 +123,7 @@ The documentation of this version of Alinea, one Markdown file per page of https
   - [TagGroup](components/tag-group.md)
   - [Text](components/text.md)
   - [TextField](components/text-field.md): A text input with a label, help text and a validation message. Set multiline for a text area that grows with its content.
-  - [TimeField](components/time-field.md)
+  - [TimeField](components/time-field.md): The value is an ISO time string: 14:30, or 14:30:15 with granularity="second".
   - [Timestamp](components/timestamp.md): A date shown relative to now, with the full date on hover.
   - [Toggle](components/toggle.md): A button that stays pressed until it is pressed again.
   - [ToggleGroup](components/toggle-group.md): A row of toggles where one or several can be pressed.

package/docs/instant-publishing.md

@@ -10,6 +10,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
@@ -23,6 +25,25 @@ 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'
 
-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.
+const handler = createHandler({
+  cms,
+  afterCommit({entries, removed}) {
+    const changed = [...entries, ...removed]
+    if (changed.some(entry => entry.type === 'Product'))
+      revalidateTag('products', 'max')
+  }
+})
+
+export const GET = handler
+export const POST = handler
+```