|
230 | 230 | }, |
231 | 231 | { |
232 | 232 | "name": "columns", |
233 | | - "type": "array" |
| 233 | + "type": "array", |
| 234 | + "description": "The fields the list shows, in order: field names (`[\"name\", \"stage\"]`) or the spec's `ListColumn` objects. They are also the query's `$select`. Optional on a page node: a node bound to a saved view through `dataSource.view` draws that view's columns." |
234 | 235 | }, |
235 | 236 | { |
236 | 237 | "name": "filter", |
237 | | - "type": "array" |
| 238 | + "type": "array", |
| 239 | + "description": "The base query filter, the spec's `ViewFilterRule` array `[{ field, operator, value }]`, lowered to `$filter`." |
238 | 240 | }, |
239 | 241 | { |
240 | 242 | "name": "sort", |
241 | | - "type": "array" |
| 243 | + "type": "array", |
| 244 | + "description": "The initial sort order, `[{ field, order }]`, lowered to `$orderby` in the order written." |
| 245 | + }, |
| 246 | + { |
| 247 | + "name": "pagination", |
| 248 | + "type": "object", |
| 249 | + "description": "The spec's pagination config, `{ pageSize, pageSizeOptions }`: `pageSize` caps each query (`$top`), and `pageSizeOptions` offers those sizes to the user." |
| 250 | + }, |
| 251 | + { |
| 252 | + "name": "searchableFields", |
| 253 | + "type": "array", |
| 254 | + "of": "string", |
| 255 | + "description": "The field names the toolbar search box searches. A term typed into the box is sent with these fields only." |
| 256 | + }, |
| 257 | + { |
| 258 | + "name": "label", |
| 259 | + "type": [ |
| 260 | + "string", |
| 261 | + "object" |
| 262 | + ], |
| 263 | + "description": "The list's label: it names the exported file and heads the record-detail overlay. A plain string, or an inline per-locale map (`{ en: \"Open tasks\", \"zh-CN\": \"未完成任务\" }`) resolved against the display locale." |
| 264 | + }, |
| 265 | + { |
| 266 | + "name": "description", |
| 267 | + "type": [ |
| 268 | + "string", |
| 269 | + "object" |
| 270 | + ], |
| 271 | + "description": "One line about the list, drawn as the toolbar's info control (its tooltip and accessible name). A plain string, or an inline per-locale map resolved against the display locale. `appearance.showDescription: false` hides it." |
| 272 | + }, |
| 273 | + { |
| 274 | + "name": "userFilters", |
| 275 | + "type": "object", |
| 276 | + "description": "The quick-filter bar above the list, the spec's `UserFilters` config: `{ element: \"dropdown\" | \"toggle\" | \"tabs\", fields | tabs }`. Each filter narrows the query." |
| 277 | + }, |
| 278 | + { |
| 279 | + "name": "userActions", |
| 280 | + "type": "object", |
| 281 | + "description": "Which toolbar controls the user gets, the spec's `UserActionsConfig` of per-control toggles: a control set to `false` (for example `sort: false`) is taken off the toolbar, and the controls it does not name stay." |
| 282 | + }, |
| 283 | + { |
| 284 | + "name": "compactToolbar", |
| 285 | + "type": "boolean", |
| 286 | + "description": "Gather the grouping, row colour, density and hide-fields controls into one Display form. On by default; `false` draws one toolbar button per control." |
| 287 | + }, |
| 288 | + { |
| 289 | + "name": "appearance", |
| 290 | + "type": "object", |
| 291 | + "description": "The spec's appearance config, `{ showDescription, allowedVisualizations }`. `showDescription: false` hides the description. `allowedVisualizations` narrows the kinds a view switcher offers, and a page node draws no switcher, so on a page it changes nothing: the node's `type` is the kind drawn." |
| 292 | + }, |
| 293 | + { |
| 294 | + "name": "exportOptions", |
| 295 | + "type": "object", |
| 296 | + "description": "The export menu, `{ formats, maxRecords, includeHeaders, fileNamePrefix, streaming }`. Declaring it offers the export on the toolbar, in the listed formats; `fileNamePrefix` names the file." |
| 297 | + }, |
| 298 | + { |
| 299 | + "name": "allowPrinting", |
| 300 | + "type": "boolean", |
| 301 | + "description": "Draw a Print button that opens the browser's print dialog for the list." |
| 302 | + }, |
| 303 | + { |
| 304 | + "name": "showRecordCount", |
| 305 | + "type": "boolean", |
| 306 | + "description": "The record count in the list's footer. On by default; `false` takes it off." |
| 307 | + }, |
| 308 | + { |
| 309 | + "name": "emptyState", |
| 310 | + "type": "object", |
| 311 | + "description": "What the list draws when no record comes back, the spec's `EmptyState`: `{ title, message, icon, link }`. `title`, `message` and the link's `label` each take a plain string or an inline per-locale map." |
| 312 | + }, |
| 313 | + { |
| 314 | + "name": "hiddenFields", |
| 315 | + "type": "array", |
| 316 | + "of": "string", |
| 317 | + "description": "Field names taken out of `columns`. A name `columns` does not show takes nothing out." |
| 318 | + }, |
| 319 | + { |
| 320 | + "name": "fieldOrder", |
| 321 | + "type": "array", |
| 322 | + "of": "string", |
| 323 | + "description": "Field names that order the columns left after `hiddenFields`. A column not listed comes after every listed one; a listed name that is not a column orders nothing." |
| 324 | + }, |
| 325 | + { |
| 326 | + "name": "rowHeight", |
| 327 | + "type": "enum", |
| 328 | + "enum": [ |
| 329 | + "compact", |
| 330 | + "short", |
| 331 | + "medium", |
| 332 | + "tall", |
| 333 | + "extra_tall" |
| 334 | + ], |
| 335 | + "description": "Row density. Absent, rows are `compact`." |
| 336 | + }, |
| 337 | + { |
| 338 | + "name": "resizable", |
| 339 | + "type": "boolean", |
| 340 | + "description": "Let users drag column borders to resize the grid's columns." |
| 341 | + }, |
| 342 | + { |
| 343 | + "name": "selection", |
| 344 | + "type": "object", |
| 345 | + "description": "Row selection, `{ type: \"none\" | \"single\" | \"multiple\" }`." |
| 346 | + }, |
| 347 | + { |
| 348 | + "name": "navigation", |
| 349 | + "type": "object", |
| 350 | + "description": "What clicking a row does, the spec's `NavigationConfig`: `{ mode: \"page\" | \"drawer\" | \"modal\" | \"split\" | \"popover\" | \"new_window\" | \"none\", … }`. An overlay mode opens the record over the list, headed by the list's `label`." |
| 351 | + }, |
| 352 | + { |
| 353 | + "name": "grouping", |
| 354 | + "type": "object", |
| 355 | + "description": "Group the rows, `{ fields: [{ field, order, collapsed }] }`. The groups and their header counts come from the server." |
| 356 | + }, |
| 357 | + { |
| 358 | + "name": "rowColor", |
| 359 | + "type": "object", |
| 360 | + "description": "Colour whole rows by a field's value, `{ field, colors: { VALUE: COLOR } }`." |
| 361 | + }, |
| 362 | + { |
| 363 | + "name": "conditionalFormatting", |
| 364 | + "type": "array", |
| 365 | + "of": "object", |
| 366 | + "description": "Row style rules, each `{ condition, style }`: a CEL `condition` over the row's `record.*` and a CSS `style` map. The first rule that matches styles the row." |
| 367 | + }, |
| 368 | + { |
| 369 | + "name": "inlineEdit", |
| 370 | + "type": "boolean", |
| 371 | + "description": "Open the grid in inline-edit mode, for users who may update the object." |
| 372 | + }, |
| 373 | + { |
| 374 | + "name": "rowActions", |
| 375 | + "type": "array", |
| 376 | + "of": "string", |
| 377 | + "description": "Names of the actions offered on each row's menu." |
| 378 | + }, |
| 379 | + { |
| 380 | + "name": "bulkActions", |
| 381 | + "type": "array", |
| 382 | + "of": "string", |
| 383 | + "description": "Names of the actions offered once rows are selected. Needs a multi-row `selection`." |
| 384 | + }, |
| 385 | + { |
| 386 | + "name": "bulkActionDefs", |
| 387 | + "type": "array", |
| 388 | + "of": "object", |
| 389 | + "description": "Full bulk-action definitions, the spec's `BulkActionDef`: a mass update (`operation: \"update\"` with a `patch`) or delete, or a named action run once for the whole selection." |
242 | 390 | }, |
243 | 391 | { |
244 | 392 | "name": "options", |
245 | | - "type": "object" |
| 393 | + "type": "object", |
| 394 | + "description": "Per-kind settings, `{ kanban, calendar, gantt, gallery, timeline, map, tree, chart }`, each judged by that kind's own block. The top-level block of the same name is the canonical spelling." |
| 395 | + }, |
| 396 | + { |
| 397 | + "name": "kanban", |
| 398 | + "type": "object", |
| 399 | + "description": "The board, the spec's kanban block: `{ groupByField, columns, titleField, summarizeField }`. `groupByField` is the lane field and `columns` the fields on each card." |
| 400 | + }, |
| 401 | + { |
| 402 | + "name": "calendar", |
| 403 | + "type": "object", |
| 404 | + "description": "The calendar, `{ startDateField, endDateField, titleField, colorField, allDayField }`." |
| 405 | + }, |
| 406 | + { |
| 407 | + "name": "gantt", |
| 408 | + "type": "object", |
| 409 | + "description": "The gantt chart, `{ startDateField, endDateField, titleField, progressField, dependenciesField }`. Both date fields are needed to draw it." |
| 410 | + }, |
| 411 | + { |
| 412 | + "name": "gallery", |
| 413 | + "type": "object", |
| 414 | + "description": "The gallery, `{ coverField, titleField, visibleFields, cardSize, … }`." |
| 415 | + }, |
| 416 | + { |
| 417 | + "name": "timeline", |
| 418 | + "type": "object", |
| 419 | + "description": "The timeline, `{ startDateField, endDateField, titleField, groupByField, colorField, scale }`." |
| 420 | + }, |
| 421 | + { |
| 422 | + "name": "map", |
| 423 | + "type": "object", |
| 424 | + "description": "The map, `{ locationField }` or `{ latitudeField, longitudeField }`, with `titleField`, `zoom` and `center`." |
| 425 | + }, |
| 426 | + { |
| 427 | + "name": "tree", |
| 428 | + "type": "object", |
| 429 | + "description": "The tree, `{ parentField, labelField, fields, defaultExpandedDepth }`." |
| 430 | + }, |
| 431 | + { |
| 432 | + "name": "chart", |
| 433 | + "type": "object", |
| 434 | + "description": "The chart a `type: \"chart\"` list draws, bound to an ADR-0021 dataset: `{ dataset, values, dimensions, chartType }`. There is no default binding." |
246 | 435 | }, |
247 | 436 | { |
248 | 437 | "name": "dataSource", |
|
1444 | 1633 | "of": "string", |
1445 | 1634 | "description": "[ADR-0066] Capabilities the user must ALL hold — names that permission sets grant through `systemPermissions`, not object actions: `read` or `update` here is an ordinary capability name, not the object's read or edit permission. When the client has resolved the user's capabilities and any of these is missing, this block does not render its content; wherever it would otherwise render, an insufficient-permissions notice takes its place. Presentation only: it authorises nothing, and the data API still serves the same data to the same user. A client that cannot resolve the user's capabilities (no permission provider, or one that does not report `systemPermissions`) renders this block as if they were held — it fails open." |
1446 | 1635 | }, |
| 1636 | + { |
| 1637 | + "name": "emptyState", |
| 1638 | + "type": "object", |
| 1639 | + "description": "What this block draws in its place when its `dataSource` binding answers no row, `{ title, message, icon, link }` — the list view's own empty-state shape: a Lucide `icon` name, a `title` (default: \"Record not found\"), a `message` (default: none) and one `link: { label, url }` the user follows (default: none), opened as a `url` action opens it. `title`, `message` and the link's `label` each accept a plain string or an inline per-locale map, resolved against the display locale. Drawn then and only then — never on a block with no `dataSource` (it reads the record page's record instead), never while the bound read is loading, and never in place of the error a failed read shows; a read the server refuses as forbidden reads as no row, so it is drawn for that too. Leave it out and a binding with no row keeps the block's own placeholder." |
| 1640 | + }, |
1447 | 1641 | { |
1448 | 1642 | "name": "dataSource", |
1449 | 1643 | "type": "object", |
|
1488 | 1682 | "of": "string", |
1489 | 1683 | "description": "[ADR-0066] Capabilities the user must ALL hold — names that permission sets grant through `systemPermissions`, not object actions: `read` or `update` here is an ordinary capability name, not the object's read or edit permission. When the client has resolved the user's capabilities and any of these is missing, this block does not render its content; wherever it would otherwise render, an insufficient-permissions notice takes its place. Presentation only: it authorises nothing, and the data API still serves the same data to the same user. A client that cannot resolve the user's capabilities (no permission provider, or one that does not report `systemPermissions`) renders this block as if they were held — it fails open." |
1490 | 1684 | }, |
| 1685 | + { |
| 1686 | + "name": "emptyState", |
| 1687 | + "type": "object", |
| 1688 | + "description": "What this block draws in its place when its `dataSource` binding answers no row, `{ title, message, icon, link }` — the list view's own empty-state shape: a Lucide `icon` name, a `title` (default: \"Record not found\"), a `message` (default: none) and one `link: { label, url }` the user follows (default: none), opened as a `url` action opens it. `title`, `message` and the link's `label` each accept a plain string or an inline per-locale map, resolved against the display locale. Drawn then and only then — never on a block with no `dataSource` (it reads the record page's record instead), never while the bound read is loading, and never in place of the error a failed read shows; a read the server refuses as forbidden reads as no row, so it is drawn for that too. Leave it out and a binding with no row keeps the block's own placeholder." |
| 1689 | + }, |
1491 | 1690 | { |
1492 | 1691 | "name": "dataSource", |
1493 | 1692 | "type": "object", |
|
1872 | 2071 | "type": "string", |
1873 | 2072 | "description": "Passed to the Button primitive; a per-action size overrides it" |
1874 | 2073 | }, |
| 2074 | + { |
| 2075 | + "name": "emptyState", |
| 2076 | + "type": "object", |
| 2077 | + "description": "What this block draws in its place when its `dataSource` binding answers no row, `{ title, message, icon, link }` — the list view's own empty-state shape: a Lucide `icon` name, a `title` (default: \"Record not found\"), a `message` (default: none) and one `link: { label, url }` the user follows (default: none), opened as a `url` action opens it. `title`, `message` and the link's `label` each accept a plain string or an inline per-locale map, resolved against the display locale. Drawn then and only then — never on a block with no `dataSource` (it reads the record page's record instead), never while the bound read is loading, and never in place of the error a failed read shows; a read the server refuses as forbidden reads as no row, so it is drawn for that too. Leave it out and a binding with no row keeps the block's own placeholder." |
| 2078 | + }, |
1875 | 2079 | { |
1876 | 2080 | "name": "dataSource", |
1877 | 2081 | "type": "object", |
|
2405 | 2609 | "enum": [ |
2406 | 2610 | "update" |
2407 | 2611 | ], |
2408 | | - "description": "`update` declares a single-record field write: the runner dispatches it to the platform action route with `patch` merged under the collected values" |
2409 | | - }, |
2410 | | - { |
2411 | | - "name": "patch", |
2412 | | - "type": "object", |
2413 | | - "description": "For `operation: update`: the field values written, merged UNDER the values the user supplies, so a collected value of the same name wins" |
| 2612 | + "description": "`update` declares a single-record field write: the row runs the declared action its `name` names, so it needs a `name`. The runner posts the collected values to the platform action route under that name, and the route writes that action's own `patch`" |
2414 | 2613 | }, |
2415 | 2614 | { |
2416 | 2615 | "name": "confirmText", |
|
2709 | 2908 | "enum": [ |
2710 | 2909 | "update" |
2711 | 2910 | ], |
2712 | | - "description": "`update` declares a single-record field write: the runner dispatches it to the platform action route with `patch` merged under the collected values" |
2713 | | - }, |
2714 | | - { |
2715 | | - "name": "patch", |
2716 | | - "type": "object", |
2717 | | - "description": "For `operation: update`: the field values written, merged UNDER the values the user supplies, so a collected value of the same name wins" |
| 2911 | + "description": "`update` declares a single-record field write: the row runs the declared action its `name` names, so it needs a `name`. The runner posts the collected values to the platform action route under that name, and the route writes that action's own `patch`" |
2718 | 2912 | }, |
2719 | 2913 | { |
2720 | 2914 | "name": "confirmText", |
|
0 commit comments