@ghentcdh/crouton-core 0.0.1-alpha.85 → 0.0.1-alpha.87

package/agent-docs/1.getting-started/manual-setup.md

@@ -326,6 +326,9 @@ const router = createRouter({
 
 const app = createApp(App);
 app.use(CroutonPlugin(api, { title: 'My App', router }));
+
+// To restrict supported languages to English only:
+// app.use(CroutonPlugin(api, { title: 'My App', router, i18n: { languages: ['en'] } }));
 app.use(router);
 app.mount('#app');
 ```

package/agent-docs/2.resources/columns.md

@@ -25,7 +25,7 @@ Both forms support the same options:
 | `createable` / `updateable`                       | Whether the field is written on create/update                                                                                                                                                                                                                                                                               |
 | `required`                                        | Whether the **form** demands a value. Overrides the Zod model in either direction on a prisma resource (`true` adds, `false` removes, omitted defers to the model); the only way to mark a field required on a `kind: "custom"` resource. Ignored on the id column and on fields that are neither createable nor updateable |
 | `displayKey`                                      | Nested field to display (e.g. `author.name`)                                                                                                                                                                                                                                                                                |
-| `showInLookup`                                    | Sets the display label when **this** resource appears as an option in another resource's autocomplete. Does **not** affect `?q=` search — use `layout.table.searchFields` for that.                                                                                                                                         |
+| `showInLookup` *(deprecated)*                     | **Use `lookup.labels` at the resource root instead** (run `crouton migrate`). Sets the display label when this resource appears as an autocomplete option in another resource. Does **not** affect `?q=` search.                                                                                                             |
 | `unique`                                          | Validate the value is unique: `true`, or `{ scope, caseInsensitive, message }`. Checks as-you-type and maps a DB unique violation to this field. Needs a matching `@unique` constraint. See [Unique fields](unique.md)                                                                                                       |
 | `column`                                          | Source column name when it differs from the key/`id` (defaults to `id`)                                                                                                                                                                                                                                                    |
 | `enum`                                            | Name of a shared enum in `crouton.enums.json`; its `{ value, label }[]` is injected into `fieldInput.options.values`                                                                                                                                                                                                        |
@@ -35,7 +35,8 @@ Both forms support the same options:
 ::: warning Moved to `layout.table`
 The following column-level options are **deprecated** and will be removed. Use `layout.table` instead:
 
-- `sortable` / `defaultSort` → `layout.table.items[{ id, sortable, defaultSort }]`
+- `sortable` → `layout.table.items[{ id, sortable }]`
+- `defaultSort` → `layout.table.defaultSort` (`{ field: "colId", sortDir: "asc" | "desc" }`)
 - `searchable` → `operations.findAll.search: ["colId"]`
 - `filterable` → `layout.table.filterFields: ["colId"]`
 - `showWhen` / `hideWhen` / `disabledWhen` → `layout.table.items[{ id, showWhen, ... }]`
@@ -217,57 +218,65 @@ Add `customComponent` to the table layout item's `options` to override the cell
 The custom cell component receives `data` (full row object), `value` (cell value), `column`, and `options` as props.
 See [Custom renderers](../4.frontend/custom-renderers.md) for how to register the component.
 
-## Calculated columns
+## Computed columns
 
-Read-only columns computed in SQL at query time. Use `main` as the alias for the resource's own table:
+Read-only columns derived from a raw SQL subquery at query time. Add a `computed` object to the column definition:
 
 ```json
 {
-  "calculatedColumns": [
-    {
-      "id": "chapter_count",
-      "alias": "chapter_count",
+  "columns": {
+    "chapter_count": {
       "label": "Chapters",
-      "type": "number",
-      "position": 5,
-      "sqlExpression": "(SELECT count(*) FROM chapter c WHERE c.book_id = main.id)"
+      "computed": {
+        "sql": "(SELECT count(*) FROM chapter c WHERE c.book_id = main.id)",
+        "type": "number"
+      }
     }
-  ]
+  }
 }
 ```
 
-| Field           | Type     | Description                                               |
-|-----------------|----------|-----------------------------------------------------------|
-| `id`            | `string` | Column id                                                 |
-| `alias`         | `string` | SQL alias — must match `id` in most cases                 |
-| `label`         | `string` | Display label                                             |
-| `type`          | `string` | Data type shorthand (`"number"`, `"string"`, etc.)         |
-| `position`      | `number` | Order among columns                                       |
-| `hiddenInTable` | `boolean`| Hide from table (still available via API)                 |
-| `sqlExpression` | `string` | The SQL subquery expression. Use `main` for the parent table alias. |
+| Field        | Type     | Description                                                                 |
+|--------------|----------|-----------------------------------------------------------------------------|
+| `sql`        | `string` | Raw SQL subquery. Use `main` as the alias for the parent table row.         |
+| `type`       | `string` | Cast type for the result: `"number"` (default), `"string"`, or `"boolean"`. |
+
+All standard column fields (`label`, `hiddenInTable`, `hiddenInView`, `position`, `fieldInput`, …) are valid alongside `computed`.
 
 ::: warning
-Calculated columns are not available on `kind: "custom"` resources — they run raw SQL against a real table.
+Computed columns are not available on `kind: "custom"` resources — they run raw SQL against a real table.
 Compute the value in `findAll` instead.
 :::
 
+::: warning Deprecated: `calculatedColumns`
+The top-level `calculatedColumns` array is removed. Run `crouton migrate` to move each entry to `columns[id].computed`.
+:::
+
 ## Includes
 
-Eagerly load relations with the list/detail queries:
+Eagerly load relations with the list/detail queries. Declare them per operation so `findAll` and `findOne` can differ:
 
 ```json
 {
-  "include": [
-    "author",
-    {
-      "relation": "chapters",
-      "orderBy": { "position": "asc" },
-      "include": ["sections"]
+  "operations": {
+    "findAll": {
+      "include": [
+        "author",
+        { "relation": "chapters", "orderBy": { "position": "asc" }, "include": ["sections"] }
+      ]
+    },
+    "findOne": {
+      "include": [
+        "author",
+        { "relation": "chapters", "orderBy": { "position": "asc" }, "include": ["sections"] }
+      ]
     }
-  ]
+  }
 }
 ```
 
+When `findOne.include` is absent, crouton falls back to `findAll.include`.
+
 | Field      | Type             | Description                                                        |
 |------------|------------------|--------------------------------------------------------------------|
 | `relation` | `string`         | Prisma relation field name                                         |
@@ -276,3 +285,7 @@ Eagerly load relations with the list/detail queries:
 
 When a relation column has a `sort` option (see [Relations](relations.md#sorting-related-records)), the loader
 automatically injects the corresponding `orderBy` into the include clause — no manual configuration needed.
+
+::: warning Deprecated: root `include`
+The top-level `include` field is removed. Run `crouton migrate` to move it to `operations.findAll.include` / `operations.findOne.include`.
+:::

package/agent-docs/2.resources/layout.md

@@ -231,6 +231,7 @@ The table node carries all table-specific settings:
     "createdAt",
     "updatedAt"
   ],
+  "searchFields": ["title", "isbn"],
   "filterFields": ["status"],
   "rowActions": [
     { "id": "approve", "label": "Approve", "type": "post" }
@@ -244,28 +245,63 @@ The table node carries all table-specific settings:
 | Field | Description |
 |---|---|
 | `items[]` | Column order + per-column overrides. Entries are field ids (strings) or field controls (objects with `id`). No nested nodes — the table is flat. |
+| `searchFields` | Column ids included in `?q=` free-text search. |
 | `filterFields` | Column ids that get a filter control in the toolbar. |
 | `rowActions` | Per-record actions (receive the record id). |
 | `tableActions` | Global toolbar actions (no record id). |
 | `title` / `label` | Heading rendered above the table. `title` wins over `label`. |
 
-::: tip Free-text search
-Free-text search (`?q=`) is declared on the operation, not the table layout. See [`operations.findAll.search`](operations.md#free-text-search).
+#### Per-column table item options
+
+| Field | Type | Description |
+|---|---|---|
+| `sortable` | boolean | Enable sort toggle on this column header. |
+| `defaultSort` | `true` \| `"asc"` \| `"desc"` | Initial sort column and direction. `true` = `"asc"`. At most one column. |
+| `width` | named (`"xs"` – `"xl"`) or CSS value | Column width. |
+| `minWidth` / `maxWidth` | CSS value | Width constraints. |
+| `align` | `"left"` \| `"center"` \| `"right"` | Cell text alignment. Number columns default to `"right"`. |
+| `truncate` | `boolean` \| number | `true` = single-line ellipsis; number = max lines before clamp. |
+| `pin` | `"left"` \| `"right"` | Sticky column. |
+| `visible` | boolean | `false` = hidden by default (still in the schema; no column chooser yet). |
+| `headerTooltip` | string | Tooltip text on the column header. |
+| `showWhen` | `{ field, eq?, neq?, exists?, notExists? }` | Show column when condition matches. |
+| `hideWhen` | Same shape | Hide column when condition matches. |
+| `disabledWhen` | Same shape | Disable column when condition matches. |
+
+`type` + `options` override the cell renderer for this column in the table only.
+
+::: tip
+`colspan`, `rowspan`, and `hideLabel` are form-layout options and have no effect on table items — they produce a validation error if set.
 :::
 
-#### Per-column table item options
+#### Table node options
 
-Beyond the standard `colspan`/`label`/`type`/`options` overrides, table items also accept:
+Beyond `items`, the table node accepts presentation options:
 
-| Field | Description |
-|---|---|
-| `sortable` | `true` to enable sort toggle on this column header. |
-| `defaultSort` | `true` to sort by this column on initial load. At most one column. |
-| `showWhen` | `{ field, eq?, neq?, exists?, notExists? }` — show column when condition matches. |
-| `hideWhen` | Same shape — hide column when condition matches. |
-| `disabledWhen` | Same shape — disable column when condition matches. |
+| Field | Type | Description |
+|---|---|---|
+| `pageSize` | number | Default page size (default `20`). Frontend hint; server still caps it. |
+| `pageSizes` | number[] | Page size selector options (e.g. `[20, 50, 100]`). |
+| `density` | `"normal"` \| `"compact"` | Row height. |
+| `selectable` | boolean | Show row checkboxes for multi-select. |
+| `rowClick` | `"view"` \| `"edit"` \| `"none"` | What happens when a row is clicked. |
+| `emptyText` | string | Message shown when there are no rows. |
 
-`type` + `options` override the cell renderer for this column in the table only.
+```json
+"table": {
+  "pageSize": 50,
+  "pageSizes": [20, 50, 100],
+  "density": "compact",
+  "rowClick": "view",
+  "emptyText": "No books yet",
+  "items": [
+    { "id": "title",       "sortable": true, "defaultSort": "desc", "width": "md", "truncate": 2 },
+    { "id": "price",       "align": "right", "width": "xs" },
+    { "id": "status",      "pin": "left" },
+    { "id": "internalRef", "visible": false }
+  ]
+}
+```
 
 ### Table column order
 
@@ -275,7 +311,7 @@ Beyond the standard `colspan`/`label`/`type`/`options` overrides, table items al
 }
 ```
 
-The `items` list is the complete set of columns for the table. Only columns listed here are rendered; unlisted columns are hidden regardless of their `hiddenInTable` flag.
+Columns present in the table but not listed here are appended in their original order.
 
 <LayoutDemo example="table-order" />
 
@@ -293,6 +329,7 @@ A `layout.table` with an outer container type (not `"table"`) wraps the table. P
       "type": "table",
       "title": "Books",
       "items": ["title", "author", { "id": "isbn", "sortable": true }, "publishedYear", "status"],
+      "searchFields": ["title", "isbn"],
       "filterFields": ["status"],
       "tableActions": [
         { "id": "searchOpenLibrary", "type": "link", "href": "https://openlibrary.org/search", "label": "Search Open Library" }
@@ -305,7 +342,7 @@ A `layout.table` with an outer container type (not `"table"`) wraps the table. P
 }
 ```
 
-All table settings (`rowActions`, `tableActions`, `filterFields`, `title`) go on the **table node**, not the wrapper.
+All table settings (`rowActions`, `tableActions`, `searchFields`, `filterFields`, `title`) go on the **table node**, not the wrapper.
 
 Wrappers can nest arbitrarily:
 
@@ -334,26 +371,49 @@ Wrappers can nest arbitrarily:
 Use the wrapper pattern when you need a custom action component alongside the table — for example a barcode scanner that creates a record directly. Each component receives a `resource` prop (the `UseResource` instance for the current table).
 :::
 
-## The layout is the full list
+## How a record opens (`layout.<form|view>.container`)
 
-When `layout.<ctx>` is defined, it is the **only** source of truth for that context. The layout lists every column that should be rendered — columns not listed are hidden, regardless of their `hiddenIn*` flag.
+The `container` key on `layout.form` and `layout.view` controls how a record opens when a row is clicked.
 
-- **Unknown id** in a layout → validation error at load time (prevents silent typos).
-- **Unlisted columns** → not rendered (use the codemod below to migrate old files).
-- **Listed column with `hiddenIn<Ctx>: true`** → rendered (the layout wins; the flag is ignored).
+```json
+"layout": {
+  "form": {
+    "container": { "mode": "modal", "size": "xl" },
+    "items": [...]
+  },
+  "view": {
+    "container": { "mode": "page" }
+  },
+  "table": {
+    "rowClick": "view",
+    "items": [...]
+  }
+}
+```
 
-This applies independently per context: a layout for `form` does not affect `table` or `view`.
+| Field | Values | Default | Description |
+|---|---|---|---|
+| `container.mode` | `"modal"` \| `"page"` | `"modal"` | How the record opens |
+| `container.size` | `"xs"` \| `"sm"` \| `"lg"` \| `"xl"` | `"sm"` | Modal width (ignored for `"page"` mode) |
 
-### Migrating existing files
+`layout.table.rowClick` decides **what** opens (`"view"`, `"edit"`, or `"none"`); the container decides **how**.
 
-If you have resource files that relied on unlisted visible columns being appended automatically, run:
+`view.component` replaces the whole detail view with a custom Vue component:
 
-```sh
-crouton migrate --dry-run   # preview changes
-crouton migrate             # apply
+```json
+"view": { "component": "BookDetail" }
 ```
 
-The codemod appends visible unlisted columns to the layout and removes hidden listed columns.
+::: tip Migration
+The old root keys `display` and `modalSize` are removed. Run `crouton migrate` to move them automatically.
+:::
+
+## Missing / extra columns
+
+- A control id that doesn't match a visible column → **skipped, dev warning logged**.
+- Visible columns not referenced anywhere in the layout → **appended at the end, dev warning logged** (nothing silently disappears).
+
+<LayoutDemo example="missing-extra" />
 
 ## Playground
 

package/agent-docs/2.resources/operations.md

@@ -20,13 +20,16 @@ Each key accepts three forms:
 | `false` | Endpoint disabled — not registered |
 | `{ "uri": "/path/{id}" }` | **External** — client calls the given route directly; crouton registers nothing |
 
-`findAll` additionally accepts an object form to configure search and filter:
+`findAll` and `findOne` additionally accept an object form to configure search, filter, and includes:
 
 | Value | Meaning |
 |-------|---------|
 | `{ "search": ["field1", "field2"] }` | Enable findAll with explicit free-text search fields |
 | `{ "filter": ["field1"] }` | Enable findAll with explicit filter fields (overrides per-column `filterable`) |
 | `{ "search": [...], "filter": [...] }` | Both |
+| `{ "include": [...] }` | Eagerly load relations for this operation (see [Includes](columns.md#includes)) |
+
+When `findOne.include` is absent, crouton falls back to `findAll.include`.
 
 ## Free-text search
 

package/agent-docs/2.resources/relations.md

@@ -1,87 +1,135 @@
 # Relations
 
-A relation is configured as a column with `fieldInput.format: "relation"` pointing to a sub-resource file:
+A relation is configured on the **column** via `column.relation`. The `fieldInput` only picks and configures the UI widget.
 
 ```json
 {
-  "column": "author_id",
-  "fieldInput": {
-    "format": "relation",
-    "relationType": "manyToOne",
-    "resource": "./author.resource"
+  "columns": {
+    "authorId": {
+      "label": "Author",
+      "relation": {
+        "resource": "./author/resource.json",
+        "type": "manyToOne",
+        "foreignKey": "authorId",
+        "displayKey": "name"
+      },
+      "fieldInput": { "type": "autocomplete" }
+    }
   }
 }
 ```
 
-`author.resource.json` describes the related resource (its columns, operations, and lookup display). Supported
-`relationType` values: `oneToOne`, `manyToOne`, `oneToMany`, `manyToMany`.
+::: tip Migration
+`fieldInput.format: "relation"`, `fieldInput.relationType`, `fieldInput.resource`, and `fieldInput.foreignKey` are removed. Run `crouton migrate` to move them to `column.relation` automatically.
+:::
+
+## column.relation reference
 
-The frontend picks the matching control automatically — an autocomplete for `manyToOne`, an editable nested table for
-`oneToMany`, and so on.
+| Field | Description |
+|---|---|
+| `resource` | Relative path to the target `resource.json` |
+| `type` | `"manyToOne"` \| `"oneToMany"` \| `"manyToMany"` |
+| `foreignKey` | FK column name (on **this** resource for manyToOne; on **target** for oneToMany) |
+| `name` | Prisma relation field name when different from the column id |
+| `displayKey` | Field on the related record shown in autocomplete / lookup |
+| `sort` | Default sort field for the related list |
+| `sortDir` | `"asc"` \| `"desc"` (default `"asc"`) |
 
-## Foreign key
+## manyToOne (autocomplete lookup)
 
-By default, the foreign key on the child model is derived as `${parentModel}Id` (camelCase), matching the standard
-Prisma convention. If the FK field in your Prisma schema uses a different name, set `foreignKey` on `fieldInput`:
+FK is on **this** resource (e.g. `book.authorId → author.id`).
+Frontend renders an autocomplete search dropdown.
 
 ```json
 {
-  "column": "section",
-  "fieldInput": {
-    "format": "relation",
-    "relationType": "oneToMany",
-    "resource": "../section/resource.json",
-    "foreignKey": "work_id"
+  "columns": {
+    "authorId": {
+      "label": "Author",
+      "relation": {
+        "resource": "./author/resource.json",
+        "type": "manyToOne",
+        "foreignKey": "authorId",
+        "displayKey": "name"
+      },
+      "fieldInput": { "type": "autocomplete" }
+    }
+  },
+  "operations": {
+    "findAll": { "include": ["author"] },
+    "findOne": { "include": ["author"] }
   }
 }
 ```
 
-When omitted, a parent model named `work` produces `foreignKey: "workId"`.
+## oneToMany (embedded panel)
 
-## Relation options
+FK is on the **target** resource (e.g. `review.bookId → book.id`).
+Frontend renders an embedded table panel inside the detail view.
 
-`fieldInput.options` accepts the following fields for relation columns:
-
-| Option              | Type                | Description                                                             |
-|---------------------|---------------------|-------------------------------------------------------------------------|
-| `displayKey`        | `string`            | Field used as the label in the relation control (e.g. `"title"`)        |
-| `direction`         | `'row' \| 'column'` | CSS flex direction for the relation button layout                       |
-| `sort`              | `string`            | Field to sort related records by, e.g. `"title"` or `"author.name"`    |
-| `sortDir`           | `'asc' \| 'desc'`   | Sort direction (default `"asc"`)                                        |
-| `customComponent`   | `string`            | Name of a custom Vue component to override the relation control         |
-
-## Sorting related records
+```json
+{
+  "columns": {
+    "reviews": {
+      "label": "Reviews",
+      "hiddenInTable": true,
+      "hiddenInForm": true,
+      "relation": {
+        "resource": "./review/resource.json",
+        "type": "oneToMany",
+        "foreignKey": "bookId",
+        "sort": "createdAt",
+        "sortDir": "desc"
+      },
+      "fieldInput": { "type": "relation" }
+    }
+  },
+  "operations": {
+    "findOne": { "include": ["reviews"] }
+  }
+}
+```
 
-Add `sort` (and optionally `sortDir`) to `fieldInput.options` to control the order of related records. This affects:
+Load oneToMany relations in `findOne.include` only — they are heavy and not needed in the list.
 
-- **Backend includes** — when the parent record is fetched, the included relation records are returned in the specified
-  order (Prisma `orderBy` inside the `include` clause).
-- **Frontend picker** — when the relation control fetches its option list, the same sort params are forwarded as query
-  parameters.
+## manyToMany
 
 ```json
 {
-  "id": "sections",
-  "label": "Sections",
-  "hiddenInForm": true,
-  "fieldInput": {
-    "format": "relation",
-    "resource": "./section/resource.json",
-    "options": {
-      "sort": "title",
-      "sortDir": "asc",
-      "displayKey": "title"
+  "columns": {
+    "tags": {
+      "label": "Tags",
+      "relation": {
+        "resource": "./tag/resource.json",
+        "type": "manyToMany",
+        "foreignKey": "bookId",
+        "name": "tags"
+      },
+      "fieldInput": { "type": "relation" }
     }
   }
 }
 ```
 
-Dotted paths work too — `"sort": "author.name"` sorts by a nested field.
+## Loading relations: operations.include
+
+Root `include` is removed. Set includes per operation:
+
+```json
+"operations": {
+  "findAll": { "include": ["author"] },
+  "findOne": { "include": ["author", { "relation": "chapters", "orderBy": { "position": "asc" } }] }
+}
+```
+
+The object form allows an `orderBy` clause when the relation's default sort isn't enough.
+
+## Detecting a relation column
+
+Use `isRelation(col)` (exported from `@ghentcdh/crouton-core`) — returns `true` when `col.relation` is set.
 
 ## `parent.idType`
 
-When a resource is mounted under a parent via `parent.param`, the parent's id type defaults to `"number"`. If the
-parent uses string/UUID ids, declare it explicitly:
+When a resource is mounted under a parent via `parent.param`, the parent's id type defaults to `"number"`. If the parent uses string/UUID ids, declare it explicitly:
 
 ```json
 {
@@ -93,62 +141,69 @@ parent uses string/UUID ids, declare it explicitly:
 
 ## Custom relation control
 
-Register a custom Vue component in the `customComponents` registry and reference it from `fieldInput.options`:
+Register a custom Vue component and reference it from `fieldInput.options`:
 
 ```json
 {
-  "column": "sections",
-  "fieldInput": {
-    "format": "relation",
-    "resource": "../section/resource.json",
-    "options": {
-      "customComponent": "work-sections",
-      "sort": "section_number",
-      "displayKey": "title"
+  "columns": {
+    "sections": {
+      "relation": {
+        "resource": "../section/resource.json",
+        "type": "oneToMany",
+        "foreignKey": "workId",
+        "sort": "sectionNumber",
+        "displayKey": "title"
+      },
+      "fieldInput": {
+        "type": "relation",
+        "options": { "customComponent": "work-sections" }
+      }
     }
   }
 }
 ```
 
 The custom component receives `wrapper`, `value` (v-model), `appliedOptions`, `schema`, and `uischema` as props.
-All `fieldInput.options` are available via `appliedOptions`.
 
 See [Custom renderers](../4.frontend/custom-renderers.md) for how to register the component.
 
 ## Complete example
 
-A full `resource.json` showing manyToOne (autocomplete) and manyToMany (embedded table) relations together:
-
 ```json
 {
   "$schema": "https://ghentcdh.github.io/crouton/schema/v1/resource.schema.json",
   "schemaVersion": 1,
   "name": "book",
-  "model": "Book",
   "title": "Books",
+  "source": { "model": "Book" },
   "columns": {
     "id": { "idField": true, "hiddenInForm": true },
-    "title": { "searchable": true, "filterable": true, "sortable": true },
+    "title": {},
     "authorId": {
       "label": "Author",
-      "searchable": true,
-      "fieldInput": {
-        "type": "autocomplete",
-        "relationType": "manyToOne",
-        "resource": "./author.resource"
-      }
+      "relation": {
+        "resource": "./author/resource.json",
+        "type": "manyToOne",
+        "foreignKey": "authorId",
+        "displayKey": "name"
+      },
+      "fieldInput": { "type": "autocomplete" }
     },
     "categories": {
       "label": "Categories",
       "hiddenInTable": true,
-      "fieldInput": {
-        "format": "relation",
-        "relationType": "manyToMany",
-        "resource": "./category.resource"
-      }
+      "relation": {
+        "resource": "./category/resource.json",
+        "type": "manyToMany",
+        "foreignKey": "bookId"
+      },
+      "fieldInput": { "type": "relation" }
     }
   },
-  "include": ["author", "categories"]
+  "operations": {
+    "findAll": { "search": ["title"], "include": ["author"] },
+    "findOne": { "include": ["author", "categories"] }
+  }
 }
 ```
 

package/agent-docs/4.frontend/styling.md

@@ -64,6 +64,20 @@ Switching themes at runtime works the daisyUI way, with a `data-theme` attribute
 <html data-theme="mytheme"></html>
 ```
 
+## Column width scale
+
+Table items and form items share a named width scale. Use these tokens in `layout.table` items (`width` field) or form items (`colspan`-equivalent):
+
+| Token | Approximate width |
+|---|---|
+| `xs` | ~4 rem |
+| `sm` | ~8 rem |
+| `md` | ~12 rem |
+| `lg` | ~18 rem |
+| `xl` | ~24 rem |
+
+You can also pass any CSS value directly (e.g. `"120px"`, `"8rem"`, `"20%"`).
+
 ## Targeted overrides
 
 The components use regular daisyUI class names (`btn`, `modal`, `table`, `drawer`, `alert`, …), so narrow tweaks are plain CSS: