@lowdefy/docs-content 6.1.0 → 7.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +7 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/validate.md +7 -4
  31. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  32. package/content/agents/agent-endpoint-tools.md +24 -0
  33. package/content/agents/agent-properties.md +13 -3
  34. package/content/agents/agent-server-hooks.md +1 -1
  35. package/content/agents/agentchat.md +43 -7
  36. package/content/agents/agentconversations.md +42 -8
  37. package/content/agents/agents-introduction.md +107 -0
  38. package/content/callback-reference/auth0logoutcallback.md +54 -0
  39. package/content/concepts/ai-agent-docs.md +455 -106
  40. package/content/concepts/blocks.md +150 -0
  41. package/content/concepts/connections-and-requests.md +402 -0
  42. package/content/concepts/custom-html.md +42 -0
  43. package/content/concepts/custom-styling.md +50 -5
  44. package/content/concepts/dynamic-page-content.md +309 -0
  45. package/content/concepts/events-and-actions.md +154 -2
  46. package/content/concepts/four-primitives.md +31 -0
  47. package/content/concepts/html-attributes.md +293 -0
  48. package/content/concepts/i18n.md +8 -3
  49. package/content/concepts/keyboard-shortcuts.md +2 -2
  50. package/content/concepts/layout-overview.md +1 -1
  51. package/content/concepts/logger.md +99 -0
  52. package/content/concepts/lowdefy-api.md +1319 -0
  53. package/content/concepts/lowdefy-schema.md +136 -3
  54. package/content/concepts/menus.md +8 -7
  55. package/content/concepts/module-authoring.md +76 -5
  56. package/content/concepts/modules.md +3 -1
  57. package/content/concepts/notifications.md +180 -0
  58. package/content/concepts/operators.md +7 -0
  59. package/content/concepts/page-and-app-state.md +252 -0
  60. package/content/concepts/page-paths.md +209 -0
  61. package/content/concepts/theming.md +582 -0
  62. package/content/connections/aigateway.md +375 -0
  63. package/content/connections/anthropic.md +169 -2
  64. package/content/connections/awss3.md +178 -2
  65. package/content/connections/axioshttp.md +181 -0
  66. package/content/connections/google.md +169 -2
  67. package/content/connections/mongodb.md +1014 -3
  68. package/content/connections/openai-connection.md +169 -2
  69. package/content/connections/sendgridmail.md +2 -0
  70. package/content/connections/smtp.md +3 -1
  71. package/content/connections/treg.md +329 -0
  72. package/content/container-blocks/affix.md +47 -7
  73. package/content/container-blocks/alert.md +76 -24
  74. package/content/container-blocks/badge.md +100 -24
  75. package/content/container-blocks/box.md +9 -9
  76. package/content/container-blocks/card.md +132 -27
  77. package/content/container-blocks/carousel.md +60 -7
  78. package/content/container-blocks/collapse.md +153 -9
  79. package/content/container-blocks/configprovider.md +35 -13
  80. package/content/container-blocks/confirmmodal.md +69 -23
  81. package/content/container-blocks/content.md +62 -98
  82. package/content/container-blocks/descriptions.md +45 -4
  83. package/content/container-blocks/drawer.md +139 -28
  84. package/content/container-blocks/dropdownmenu.md +119 -31
  85. package/content/container-blocks/flex.md +40 -62
  86. package/content/container-blocks/footer.md +15 -11
  87. package/content/container-blocks/googlemapsheatmap.md +1 -1
  88. package/content/container-blocks/googlemapsscript.md +2 -2
  89. package/content/container-blocks/header.md +71 -36
  90. package/content/container-blocks/label.md +34 -7
  91. package/content/container-blocks/layout.md +52 -34
  92. package/content/container-blocks/masonry.md +17 -71
  93. package/content/container-blocks/mobilemenu.md +131 -88
  94. package/content/container-blocks/modal.md +161 -26
  95. package/content/container-blocks/pageheadermenu.md +138 -31
  96. package/content/container-blocks/pagesidebarlayout.md +230 -27
  97. package/content/container-blocks/pagesidermenu.md +153 -43
  98. package/content/container-blocks/popover.md +34 -31
  99. package/content/container-blocks/result.md +32 -21
  100. package/content/container-blocks/sider.md +85 -122
  101. package/content/container-blocks/span.md +7 -7
  102. package/content/container-blocks/spinner.md +3 -3
  103. package/content/container-blocks/splitter.md +150 -68
  104. package/content/container-blocks/tabs.md +64 -12
  105. package/content/container-blocks/tooltip.md +22 -46
  106. package/content/container-blocks/watermark.md +22 -4
  107. package/content/controls/parallel_for.md +21 -2
  108. package/content/controls/reject.md +24 -3
  109. package/content/controls/return.md +17 -1
  110. package/content/controls/throw.md +1 -0
  111. package/content/controls/try.md +4 -2
  112. package/content/controls/while.md +46 -0
  113. package/content/deployment/deployment-environments.md +10 -7
  114. package/content/deployment/docker.md +22 -7
  115. package/content/deployment/node-server.md +4 -0
  116. package/content/deployment/vercel.md +17 -6
  117. package/content/display-blocks/aggrid.md +36 -19
  118. package/content/display-blocks/anchor.md +16 -15
  119. package/content/display-blocks/avatar.md +57 -37
  120. package/content/display-blocks/breadcrumb.md +70 -21
  121. package/content/display-blocks/button.md +93 -19
  122. package/content/display-blocks/calendar.md +12 -0
  123. package/content/display-blocks/clickablehtml.md +239 -0
  124. package/content/display-blocks/dangeroushtml.md +1 -1
  125. package/content/display-blocks/difflist.md +1 -1
  126. package/content/display-blocks/difftimeline.md +1 -1
  127. package/content/display-blocks/divider.md +64 -3
  128. package/content/display-blocks/dropdownbutton.md +81 -30
  129. package/content/display-blocks/echart.md +35 -1
  130. package/content/display-blocks/eventlog.md +363 -0
  131. package/content/display-blocks/floatbutton.md +129 -42
  132. package/content/display-blocks/html.md +61 -1
  133. package/content/display-blocks/icon.md +250 -67
  134. package/content/display-blocks/img.md +2 -2
  135. package/content/display-blocks/menu.md +146 -73
  136. package/content/display-blocks/message.md +38 -124
  137. package/content/display-blocks/notification.md +94 -222
  138. package/content/display-blocks/paragraph.md +59 -9
  139. package/content/display-blocks/pollingtimer.md +263 -0
  140. package/content/display-blocks/progress.md +96 -17
  141. package/content/display-blocks/qrcode.md +19 -4
  142. package/content/display-blocks/s3download.md +1 -1
  143. package/content/display-blocks/search.md +19 -9
  144. package/content/display-blocks/skeletonbutton.md +1 -0
  145. package/content/display-blocks/skeletoninput.md +1 -0
  146. package/content/display-blocks/statistic.md +75 -17
  147. package/content/display-blocks/steps.md +58 -25
  148. package/content/display-blocks/table.md +2527 -0
  149. package/content/display-blocks/tablelight.md +621 -0
  150. package/content/display-blocks/tag.md +102 -17
  151. package/content/display-blocks/title.md +50 -11
  152. package/content/display-blocks/tour.md +33 -23
  153. package/content/input-blocks/autocomplete.md +81 -9
  154. package/content/input-blocks/buttonselector.md +45 -8
  155. package/content/input-blocks/captcha.md +40 -0
  156. package/content/input-blocks/checkboxselector.md +97 -7
  157. package/content/input-blocks/checkboxswitch.md +33 -3
  158. package/content/input-blocks/colorselector.md +63 -14
  159. package/content/input-blocks/daterangeselector.md +165 -45
  160. package/content/input-blocks/dateselector.md +139 -41
  161. package/content/input-blocks/datetimeselector.md +158 -49
  162. package/content/input-blocks/inputgallery.md +3 -3
  163. package/content/input-blocks/intentinput.md +207 -0
  164. package/content/input-blocks/monthselector.md +120 -52
  165. package/content/input-blocks/multipleselector.md +150 -39
  166. package/content/input-blocks/numberinput.md +98 -12
  167. package/content/input-blocks/pagination.md +70 -14
  168. package/content/input-blocks/paragraphinput.md +51 -37
  169. package/content/input-blocks/passwordinput.md +60 -6
  170. package/content/input-blocks/phonenumberinput.md +59 -26
  171. package/content/input-blocks/placesautocomplete.md +319 -0
  172. package/content/input-blocks/radioselector.md +83 -7
  173. package/content/input-blocks/ratingslider.md +57 -26
  174. package/content/input-blocks/s3uploadbutton.md +24 -24
  175. package/content/input-blocks/s3uploaddragger.md +3 -3
  176. package/content/input-blocks/s3uploadphoto.md +5 -5
  177. package/content/input-blocks/segmentedselector.md +72 -32
  178. package/content/input-blocks/selector.md +109 -21
  179. package/content/input-blocks/switch.md +65 -17
  180. package/content/input-blocks/tableinput.md +445 -0
  181. package/content/input-blocks/tagmultipleselector.md +114 -0
  182. package/content/input-blocks/tagselector.md +114 -0
  183. package/content/input-blocks/textarea.md +32 -3
  184. package/content/input-blocks/textinput.md +70 -29
  185. package/content/input-blocks/tiptapinput.md +1 -1
  186. package/content/input-blocks/tiptapmentioninput.md +2 -2
  187. package/content/input-blocks/titleinput.md +39 -12
  188. package/content/input-blocks/treeinput.md +49 -25
  189. package/content/input-blocks/treemultipleselector.md +127 -10
  190. package/content/input-blocks/treeselector.md +97 -9
  191. package/content/input-blocks/upload.md +64 -15
  192. package/content/input-blocks/uploaddragger.md +17 -1
  193. package/content/input-blocks/uploadphoto.md +18 -1
  194. package/content/input-blocks/weekselector.md +120 -55
  195. package/content/learn/introduction.md +27 -0
  196. package/content/learn/quickstart.md +53 -0
  197. package/content/list-blocks/controlledlist.md +24 -15
  198. package/content/list-blocks/list.md +11 -11
  199. package/content/list-blocks/masonrylist.md +7 -34
  200. package/content/migration/auth-upgrade.md +337 -0
  201. package/content/migration/upgrade-guide.md +1 -0
  202. package/content/migration/v3-to-v4.md +417 -0
  203. package/content/migration/v6-to-v7.md +620 -0
  204. package/content/operators/_agent.md +155 -0
  205. package/content/operators/_app.md +2 -1
  206. package/content/operators/_array.md +122 -1
  207. package/content/operators/_build.md +1 -0
  208. package/content/operators/_credential.md +57 -0
  209. package/content/operators/_cron.md +292 -0
  210. package/content/operators/_date.md +2 -0
  211. package/content/operators/_error.md +24 -1
  212. package/content/operators/_get.md +6 -6
  213. package/content/operators/_hmac.md +78 -0
  214. package/content/operators/_js.md +2 -1
  215. package/content/operators/_location.md +1 -1
  216. package/content/operators/_media.md +13 -0
  217. package/content/operators/_module.md +56 -2
  218. package/content/operators/_operator.md +17 -3
  219. package/content/operators/_path_params.md +82 -0
  220. package/content/operators/_ref.md +258 -0
  221. package/content/operators/_request.md +1 -1
  222. package/content/operators/_request_details.md +6 -0
  223. package/content/operators/_type.md +14 -3
  224. package/content/operators/_url_query.md +2 -0
  225. package/content/operators/_user.md +3 -3
  226. package/content/plugins/plugins-actions.md +10 -0
  227. package/content/plugins/plugins-connections.md +25 -0
  228. package/content/plugins/plugins-dev.md +66 -0
  229. package/content/plugins/plugins-icon-sets.md +267 -0
  230. package/content/plugins/plugins-introduction.md +27 -1
  231. package/content/plugins/plugins.md +19 -0
  232. package/content/plugins/posthog.md +359 -0
  233. package/content/provider-reference/auth-js-providers.md +107 -0
  234. package/content/provider-reference/openidconnectprovider.md +44 -0
  235. package/content/recipes/recipes.md +16 -0
  236. package/content/reference/actions-reference.md +31 -0
  237. package/content/reference/blocks-reference.md +35 -0
  238. package/content/reference/cli.md +403 -0
  239. package/content/reference/connections-reference.md +23 -0
  240. package/content/reference/operators-reference.md +47 -0
  241. package/content/reference/reference.md +16 -0
  242. package/content/reference/schema-reference.md +12 -0
  243. package/content/testing/config-tests.md +677 -0
  244. package/content/testing/e2e-configuration.md +31 -1
  245. package/content/testing/e2e-getting-started.md +1 -1
  246. package/content/testing/e2e-introduction.md +1 -1
  247. package/content/testing/e2e-writing-tests.md +12 -1
  248. package/content/testing/explore-pull-request.md +136 -0
  249. package/content/testing/journey-data-sets.md +326 -0
  250. package/content/tutorial/tutorial-actions-operators.md +2 -2
  251. package/content/tutorial/tutorial-add-blocks.md +2 -2
  252. package/content/tutorial/tutorial-create-page.md +48 -2
  253. package/content/tutorial/tutorial-display-data-page.md +3 -3
  254. package/content/tutorial/tutorial-requests-api.md +155 -0
  255. package/content/tutorial/tutorial-requests-sql.md +153 -0
  256. package/content/tutorial/tutorial-start.md +66 -1
  257. package/content/user-authentication/auth-configuration.md +267 -0
  258. package/content/user-authentication/auth-providers.md +24 -0
  259. package/content/user-authentication/auth-steps.md +141 -0
  260. package/content/user-authentication/login-and-logout.md +160 -8
  261. package/content/user-authentication/mcp-oauth.md +424 -0
  262. package/content/user-authentication/organizations.md +246 -0
  263. package/content/user-authentication/protected-pages-apis.md +97 -0
  264. package/content/user-authentication/roles.md +49 -0
  265. package/content/user-authentication/two-factor.md +229 -0
  266. package/content/user-authentication/user-object.md +58 -0
  267. package/content/user-authentication/users-introduction.md +8 -0
  268. package/content/websockets/websocket-publish.md +105 -0
  269. package/content/websockets/websocket-subscriptions.md +136 -0
  270. package/content/websockets/websockets-introduction.md +101 -0
  271. package/hazards.json +44 -0
  272. package/index.json +3691 -14
  273. package/package.json +11 -1
  274. package/scripts/collectImportedFiles.js +80 -0
  275. package/scripts/extractAgentDocs.js +41 -30
  276. package/scripts/hashDocSources.js +38 -0
  277. package/scripts/isRedirectPage.js +26 -0
  278. package/scripts/recordSourceHashes.js +100 -0
  279. package/scripts/resolvePageSections.js +42 -0
  280. package/scripts/sectionKind.js +27 -0
  281. package/content/concepts/cli.md +0 -223
  282. package/content/other/introduction.md +0 -39
  283. package/content/other/next-auth-providers.md +0 -3
  284. /package/content/{other → actions}/updatesession.md +0 -0
@@ -0,0 +1,2527 @@
1
+ # Table
2
+
3
+ A virtualised, keyboard-accessible data table for record lists, reports, pickers, trees and queues: typed cells, sorting, column filters, search, resizing, reordering, pinning, grouping with aggregates, row selection with bulk actions, inline editing, saved views and server-side data in blocks through `MongoDBTableQuery`. Its value is its UI state, `{ view, selected, expanded }`, so `_state: <id>.selected` is the selection and `_state: <id>.view` the current view. Every TableLight config is a valid Table config, and the AgGrid blocks remain supported alongside it.
4
+
5
+ ## Choosing a table block
6
+
7
+ Lowdefy has four table blocks. Pick by what the table is for, not by how many features you might need one day: `TableLight` and `Table` share one column model, so a table that outgrows `TableLight` changes `type` and keeps its config.
8
+
9
+ | Block | Use it for | Value | Rows |
10
+ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
11
+ | [`TableLight`](/TableLight) | The odd table on a page: recent orders on a dashboard, the lines of an invoice. Typed cells, header sort, row links, row buttons, a summary row. | none | tens to hundreds; a dev warning above 1,000 |
12
+ | `Table` | Record lists, reports, pickers, trees and queues: filters, search, resize, reorder, pin, grouping, selection, bulk actions, inline editing, saved views, server-side data. | `{ view, selected, expanded }` | any number (virtualised; server mode for collections too big for the browser) |
13
+ | [`TableInput`](/TableInput) | Editing a list of rows in a form: invoice lines, recipe ingredients, the steps of a plan. | the changes to `data`, `{ updated, added, removed, moved?, order? }` | as `Table` (client data only) |
14
+ | [`AgGrid`](/AgGrid) | Existing AG Grid tables, and AG Grid options that `Table` does not have. | `AgGrid*Input` holds the rows | any number |
15
+
16
+ The AgGrid blocks are not deprecated and nothing needs to move. Column config moves over by hand when you want it to: the `cell` option names match AgGrid's `cell` keys, so lift `cell.type` to the column's `type`.
17
+
18
+ `Table` takes every `TableLight` property with the same meaning. One difference: `pagination` is off by default on `Table`, which scrolls any number of rows, and on by default on `TableLight`, which shows a pager when there are more rows than `pageSize`.
19
+
20
+ ## How Table works
21
+
22
+ `Table` is an input block whose value is its UI state, not its data:
23
+
24
+ ```yaml
25
+ view: # what the user sees: columns, sort, filter, search, grouping, density
26
+ columns: [{ key: name, width: 260, pinned: start }, { key: stage }, { key: amount }]
27
+ sort: [{ key: amount, desc: true }]
28
+ filter: { key: stage, op: in, value: [lead, qualified] }
29
+ search: acme
30
+ selected: [d1, d7] # the selected row keys
31
+ expanded: [] # the expanded tree rows or detail rows
32
+ ```
33
+
34
+ - `_state: deals.selected` is always the selection and `_state: deals.view` always the current view, with no `onChange` wiring.
35
+ - Setting them sets the table: `SetState: { deals.selected: [] }` clears the selection, `SetState: { deals.view.filter: { key: stage, op: eq, value: won } }` filters it, and `Reset` returns to `defaultView`.
36
+ - Rows come from `data`: a list of rows (client mode), or `{ mode: server, request }` (server mode, below).
37
+ - `rowKey` names the field that identifies a row: `_id` by default, then `id`. Selection, expansion, events and edits all use it, so give rows a key. Rows with neither field get a key per row object, which does not survive a refetch.
38
+
39
+ The table loads its code (TanStack Table and Virtual, about 47 kB gzipped) the first time a `Table` or `TableInput` mounts, showing its loading skeleton until then (see [Loading states](#loading-states)). A page without one does not load it.
40
+
41
+ ## What is on by default
42
+
43
+ A `Table` with only `columns` and `data` already does what users expect of a table. Features that need your intent, a place to save something, or page chrome are one key away.
44
+
45
+ | Feature | Default | Turn it off or on |
46
+ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
47
+ | Sort by header click (Shift+click adds a level) | on | `sortable: false` on a column, or `defaultColumn: { sortable: false }` |
48
+ | Column resize by dragging a header edge | on | `resizable: false`, or `defaultColumn: { resizable: false }` |
49
+ | Column reorder by dragging a header | on | `reorderable: false` |
50
+ | Header menu: sort, filter, group, pin, freeze, autosize, hide, Columns… | on | `headerMenu: false` |
51
+ | Column filters (from the header menu; the header shows an icon while one applies) | on | `filterable: false`, or `defaultColumn: { filterable: false }` |
52
+ | Column manager (Columns… in the header menu) | on | follows `headerMenu` |
53
+ | Sticky header | on | `stickyHeader: false` |
54
+ | Virtualisation | `auto`: rows above 200, columns above 20 or wider than twice the viewport | `virtual: true` or `virtual: false` |
55
+ | Keyboard navigation, focus ring, ARIA grid roles | on | `keyboard: false` (the roles stay) |
56
+ | Copy with Cmd/Ctrl+C | on | always on, also with `keyboard: false` |
57
+ | Text wrap | off: text stays on one line | `wrap` or `ellipsis` on a column, `view.wrap`, or the toolbar Wrap toggle (`toolbar.density`) |
58
+ | Hover highlight, empty state, loading states | on | `emptyText`, the `empty` slot, `loading`, the block's `skeleton` |
59
+ | Summary footer | on when a column has an `aggregate` (or the view has `aggregates`) | `summary: false`; `summaryRow` shows a row the app computed instead |
60
+ | Height | grows with its rows up to `maxHeight` (600px), then scrolls | `height` for a fixed height |
61
+ | Toolbar | off | `toolbar: true` (every item) or `toolbar: { search: true, ... }` |
62
+ | Row selection | off | `rowSelection: { type: checkbox }` |
63
+ | Grouping | off | `groupable: true` on columns |
64
+ | Editing | off | `editable: true` on columns |
65
+ | Pagination | off | `pagination: true` |
66
+ | View persistence | off | `persist: { key }` |
67
+ | Saved views, server mode | off | `views`, `data: { mode: server }` |
68
+
69
+ Changes a user makes with the default features (sort, widths, order, filters, hidden columns) live in the table value for the session. `Reset` and `SetState` still control them, and they outlive a page reload only with `persist`.
70
+
71
+ ## Loading states
72
+
73
+ The table shows what it is doing while data loads, the same way in `Table`, `TableInput` and `TableLight`, so switching `type` looks the same. It reads one signal: `loading`. Lowdefy sets it while the block's or a parent's `onMount` actions run, and you set it with the `loading` property.
74
+
75
+ | `loading` | Rows | The table shows |
76
+ | --------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
77
+ | true | none yet | **Initial:** the real header over skeleton rows that fill the body |
78
+ | true | rows on screen | **Refreshing:** the rows stay, and a thin progress bar runs under the header |
79
+ | false | none (`[]`, or `data` null or missing) | **Empty:** "No rows" (`emptyText`), or "No matching rows" with _Clear filters_ when a filter or search is set |
80
+ | false | rows | **Ready** |
81
+
82
+ **Wire `loading` to the request.** A request that runs again makes `_request` return `null` until the new response lands (unless the `Request` action sets `holdValue: true`). The table holds its rows while `loading` is true, so a refetch never flashes empty, either way:
83
+
84
+ ```yaml
85
+ - id: deals
86
+ type: Table
87
+ properties:
88
+ loading:
89
+ _request_details: deals_list.0.loading # the latest call of the request
90
+ data:
91
+ _request: deals_list
92
+ columns: [name, stage, amount]
93
+ ```
94
+
95
+ Set `loading` as the property rather than the block's own `loading` key. Either way the blocks in the table's slots (toolbar buttons, bulk actions, the empty state) keep only their own loading: the table's loading, including a page `onMount` that fetches its rows, never disables them, so a "New deal" or refresh button stays usable while the rows load. Without `loading`, a table whose request failed or has not run yet shows its empty state, never a skeleton that never ends. A table on a page whose `onMount` fetches its data is loading until those actions finish, so it shows the skeleton meanwhile.
96
+
97
+ - **Skeleton rows** are shaped like their cells, so nothing jumps when the rows land: text bars of varied width, short end-aligned bars for numbers, a circle and a bar for avatars and people, pills for tags and statuses, squares for booleans and checkboxes, one small square per button (none for `showOn: hover` buttons, which are hidden until hover anyway) and a thin bar for progress; square avatars (`shape: square`) load as squares. They fill the table's height (`height`, or `maxHeight` for a table that grows with its rows), at most a page when paginated, at the current density. A shimmer band in the theme's fill colour runs across them, as on the Skeleton block, and stops when the user prefers reduced motion.
98
+ - **Timing.** The skeleton shows 120 ms after loading starts, so a fast response never flashes it, and once shown it stays at least 300 ms, so it never flickers. A key, click or focus in the table during that time shows the rows at once, so a header click or an arrow key acts on the rows. The progress bar fades in after the same 120 ms.
99
+ - **View changes.** A sort, filter, search, group or view tab the user picks keeps the old rows on screen with the progress bar; if the new rows take longer than 300 ms, the old rows dim until they arrive. A background refetch or a server `refresh` never dims.
100
+ - **While the first rows load** the toolbar's search, filters, views and slot blocks stay usable; Export, the select-all checkbox and the bulk bar wait for rows, and the record count shows a placeholder until it has a count (while refreshing it keeps the count of the rows on screen). The grid is `aria-busy`, and a polite live region says "Loading rows", then "N rows loaded".
101
+ - **The table's own code.** `Table` and `TableInput` load their code on first mount. Until it arrives the block shows this same skeleton, built from the column config, so the swap to the table moves nothing.
102
+ - **Server mode.** Rows not loaded yet (a fast scroll) are skeleton rows. An expanded group shows a spinner in its chevron and skeleton rows until its rows land. A block of rows that fails to load is one row, "Couldn't load rows · Retry": Retry loads just that block again, and the rows already loaded stay. The table shows the failure itself, so the page shows no error message for it; the error is still logged.
103
+ - **Trees.** A lazy expand (`onRowExpand` with `needsChildren`) is awaited: the chevron spins and a skeleton child row shows until the children arrive. If the actions fail, the row collapses and its chevron shows the error.
104
+ - **Actions.** Cell saves, row moves and TableInput edits show their own saving and error markers. Export spins while the file builds (in server mode, while the `onExport` actions run). The filter builder, column filters, column manager, header menu and cell editor open at once, with a spinner inside them the first time their code loads.
105
+
106
+ **A different loading look.** A block's `skeleton` config replaces the whole table while the block is loading, as for any Lowdefy block (with the block's own `loading` key, or while `onMount` runs):
107
+
108
+ ```yaml
109
+ - id: deals
110
+ type: Table
111
+ skeleton:
112
+ type: Skeleton
113
+ properties:
114
+ height: 320
115
+ properties:
116
+ data:
117
+ _request: deals_list
118
+ columns: [name, stage, amount]
119
+ ```
120
+
121
+ ## Table types
122
+
123
+ ### Embedded table
124
+
125
+ A few lines on a record page. No toolbar, no persistence; virtualisation stays off below 200 rows.
126
+
127
+ ```yaml
128
+ - id: line_items
129
+ type: Table
130
+ properties:
131
+ data:
132
+ _request: get_invoice.0.lines
133
+ size: compact
134
+ columns:
135
+ - key: product
136
+ - key: qty
137
+ type: number
138
+ width: 90
139
+ aggregate: sum
140
+ - key: price
141
+ type: currency
142
+ cell:
143
+ currency: EUR
144
+ - key: total
145
+ type: currency
146
+ cell:
147
+ currency: EUR
148
+ aggregate: sum
149
+ ```
150
+
151
+ This is also a valid `TableLight`. Use `TableLight` when it needs nothing more.
152
+
153
+ ### Record list (CRM index view)
154
+
155
+ A list of deals from a MongoDB collection, loaded in blocks as the user scrolls, with row links, a toolbar, saved views, bulk actions, hover buttons and one editable column. The requests come first, then the table.
156
+
157
+ ```yaml
158
+ id: deals
159
+ type: PageHeaderMenu
160
+ properties:
161
+ title: Deals
162
+
163
+ requests:
164
+ # The rows. The table fires this request with { startRow, endRow, view, groupPath }; the
165
+ # payload reads them from the event and the properties from the payload.
166
+ - id: deals_page
167
+ type: MongoDBTableQuery
168
+ connectionId: deals
169
+ payload:
170
+ view:
171
+ _event: view
172
+ startRow:
173
+ _event: startRow
174
+ endRow:
175
+ _event: endRow
176
+ groupPath:
177
+ _event: groupPath
178
+ timezone: # date filters compare the user's days
179
+ _js: 'return Intl.DateTimeFormat().resolvedOptions().timeZone;'
180
+ properties:
181
+ pipeline: # always runs first: the view can only narrow it
182
+ - $match:
183
+ org_id:
184
+ _user: organization.id
185
+ archived:
186
+ $ne: true
187
+ # The allowlist, keyed by column key. The bulk request below uses the same fields, so they
188
+ # live in one file:
189
+ # name: { type: text, search: true }
190
+ # stage: { type: status, groupable: true }
191
+ # owner: { type: avatar, path: owner.name, search: true, groupable: true }
192
+ # amount: { type: currency }
193
+ # updated: { type: date }
194
+ fields:
195
+ _ref: deals/table_fields.yaml
196
+ # Rows return _id and the fields' paths only; add the paths cells read on their own.
197
+ returnFields:
198
+ - owner.avatar
199
+ user:
200
+ _user: true
201
+ timezone:
202
+ _payload: timezone
203
+ view:
204
+ _payload: view
205
+ startRow:
206
+ _payload: startRow
207
+ endRow:
208
+ _payload: endRow
209
+ groupPath:
210
+ _payload: groupPath
211
+
212
+ # Saved views: the user's own, and the ones shared in the organization.
213
+ - id: deal_views
214
+ type: MongoDBAggregation
215
+ connectionId: table_views
216
+ properties:
217
+ pipeline:
218
+ - $match:
219
+ table: deals
220
+ org_id:
221
+ _user: organization.id
222
+ $or:
223
+ - owner_id:
224
+ _user: id
225
+ - shared: true
226
+ - $sort:
227
+ title: 1
228
+ - $project:
229
+ _id: 0
230
+ id: $_id
231
+ title: 1
232
+ view: 1
233
+ shared: 1
234
+ locked: # only the owner may save over or delete a view
235
+ $ne:
236
+ - $owner_id
237
+ - _user: id
238
+
239
+ - id: save_deal_view
240
+ type: MongoDBUpdateOne
241
+ connectionId: table_views
242
+ payload:
243
+ id:
244
+ _state: view_id
245
+ title:
246
+ _event: title
247
+ shared:
248
+ _event: shared
249
+ view:
250
+ _event: view
251
+ properties:
252
+ filter:
253
+ _id:
254
+ _payload: id
255
+ owner_id:
256
+ _user: id
257
+ update:
258
+ $set:
259
+ title:
260
+ _payload: title
261
+ shared:
262
+ _payload: shared
263
+ view:
264
+ _payload: view
265
+ $setOnInsert:
266
+ table: deals
267
+ org_id:
268
+ _user: organization.id
269
+ options:
270
+ upsert: true
271
+
272
+ - id: delete_deal_view
273
+ type: MongoDBDeleteOne
274
+ connectionId: table_views
275
+ payload:
276
+ id:
277
+ _event: id
278
+ properties:
279
+ filter:
280
+ _id:
281
+ _payload: id
282
+ owner_id:
283
+ _user: id
284
+
285
+ # Inline edit of the stage column.
286
+ - id: update_deal_stage
287
+ type: MongoDBUpdateOne
288
+ connectionId: deals
289
+ payload:
290
+ _id:
291
+ _event: rowKey
292
+ stage:
293
+ _event: value
294
+ properties:
295
+ filter:
296
+ _id:
297
+ _payload: _id
298
+ org_id:
299
+ _user: organization.id
300
+ update:
301
+ $set:
302
+ stage:
303
+ _payload: stage
304
+ updated:
305
+ _date: now
306
+
307
+ # A hover button.
308
+ - id: archive_deal
309
+ type: MongoDBUpdateOne
310
+ connectionId: deals
311
+ payload:
312
+ _id:
313
+ _event: rowKey
314
+ properties:
315
+ filter:
316
+ _id:
317
+ _payload: _id
318
+ org_id:
319
+ _user: organization.id
320
+ update:
321
+ $set:
322
+ archived: true
323
+
324
+ # A bulk action over the selection: a list of keys, or every row matching the view.
325
+ - id: assign_deals
326
+ type: MongoDBTableChanges
327
+ connectionId: deals
328
+ payload:
329
+ selected:
330
+ _state: deals_table.selected
331
+ timezone:
332
+ _js: 'return Intl.DateTimeFormat().resolvedOptions().timeZone;'
333
+ properties:
334
+ filter:
335
+ org_id:
336
+ _user: organization.id
337
+ fields: # what the bulk write may set, keyed by field path
338
+ owner.name:
339
+ type: text
340
+ owner.id:
341
+ type: text
342
+ queryFields: # the table's MongoDBTableQuery fields, to read an all-matching selection
343
+ _ref: deals/table_fields.yaml
344
+ user:
345
+ _user: true
346
+ timezone:
347
+ _payload: timezone
348
+ selection:
349
+ _payload: selected
350
+ set:
351
+ owner.name:
352
+ _user: name
353
+ owner.id:
354
+ _user: id
355
+
356
+ events:
357
+ onMount:
358
+ - id: fetch_views
359
+ type: Request
360
+ params: deal_views
361
+
362
+ blocks:
363
+ - id: deals_table
364
+ type: Table
365
+ properties:
366
+ height: calc(100vh - 220px)
367
+ data:
368
+ mode: server
369
+ request: deals_page
370
+ rowLink:
371
+ pageId: deal
372
+ urlQuery:
373
+ _id: _id
374
+ rowSelection:
375
+ type: checkbox
376
+ views:
377
+ _request: deal_views
378
+ activeView:
379
+ _state: active_view
380
+ persist:
381
+ key: deals
382
+ toolbar:
383
+ views: true
384
+ search: true
385
+ quickFilters: [stage]
386
+ filter: true
387
+ sort: true
388
+ group: true
389
+ columns: true
390
+ density: true
391
+ defaultView:
392
+ sort:
393
+ - key: updated
394
+ desc: true
395
+ columns:
396
+ - key: name
397
+ title: Deal
398
+ width: 260
399
+ pinned: start
400
+ - key: stage
401
+ type: status
402
+ groupable: true
403
+ editable: true
404
+ options:
405
+ lead: Lead
406
+ qualified:
407
+ label: Qualified
408
+ color: processing
409
+ won:
410
+ label: Won
411
+ color: success
412
+ lost:
413
+ label: Lost
414
+ color: error
415
+ - key: owner
416
+ field: owner.name
417
+ type: avatar
418
+ groupable: true
419
+ cell:
420
+ srcField: owner.avatar # returned through returnFields
421
+ - key: amount
422
+ type: currency
423
+ aggregate: sum
424
+ - key: updated
425
+ type: date
426
+ cell:
427
+ relative: true
428
+ - key: actions
429
+ type: buttons
430
+ title: ''
431
+ width: 56
432
+ pinned: end
433
+ sortable: false
434
+ filterable: false
435
+ cell:
436
+ showOn: hover
437
+ buttons:
438
+ - eventName: onArchive
439
+ title: Archive
440
+ icon: Archive
441
+ hideTitle: true
442
+ slots:
443
+ toolbarStart:
444
+ blocks:
445
+ - id: new_deal
446
+ type: Button
447
+ properties:
448
+ title: New deal
449
+ icon: add
450
+ size: small
451
+ events:
452
+ onClick:
453
+ - id: go_new
454
+ type: Link
455
+ params:
456
+ pageId: new-deal
457
+ bulkActions:
458
+ blocks:
459
+ - id: assign_to_me
460
+ type: Button
461
+ properties:
462
+ title: Assign to me
463
+ size: small
464
+ events:
465
+ onClick:
466
+ - id: assign
467
+ type: Request
468
+ params: assign_deals
469
+ - id: refresh
470
+ type: CallMethod
471
+ params:
472
+ blockId: deals_table
473
+ method: refresh
474
+ - id: clear
475
+ type: CallMethod
476
+ params:
477
+ blockId: deals_table
478
+ method: clearSelection
479
+ events:
480
+ onCellEdit:
481
+ - id: save_stage
482
+ type: Request
483
+ params: update_deal_stage
484
+ onArchive:
485
+ - id: archive
486
+ type: Request
487
+ params: archive_deal
488
+ - id: drop_row
489
+ type: CallMethod
490
+ params:
491
+ blockId: deals_table
492
+ method: applyTransaction
493
+ args:
494
+ - remove:
495
+ - _event: rowKey
496
+ onViewSelect:
497
+ - id: remember_view
498
+ type: SetState
499
+ params:
500
+ active_view:
501
+ _event: id
502
+ onViewSave:
503
+ # Save passes the active view's id; Save as passes none, so it gets a new one.
504
+ - id: view_id
505
+ type: SetState
506
+ params:
507
+ view_id:
508
+ _if_none:
509
+ - _event: id
510
+ - _uuid: true
511
+ - id: save_view
512
+ type: Request
513
+ params: save_deal_view
514
+ - id: refetch_views
515
+ type: Request
516
+ params: deal_views
517
+ - id: select_saved
518
+ type: SetState
519
+ params:
520
+ active_view:
521
+ _state: view_id
522
+ onViewDelete:
523
+ - id: delete_view
524
+ type: Request
525
+ params: delete_deal_view
526
+ - id: refetch_after_delete
527
+ type: Request
528
+ params: deal_views
529
+ ```
530
+
531
+ The connections are `MongoDBCollection` connections to the `deals` and `table_views` collections with `write: true`.
532
+
533
+ What each part does:
534
+
535
+ - **Server mode.** The table fetches rows 0 to 200 on mount, then each block of `blockSize` rows (default 200) as it scrolls into view, keeping at most `maxBlocks` blocks (default 20). A sort, filter, search or grouping change fetches from the top, and the old rows stay on screen, dimmed, until the new ones land. See [MongoDBTableQuery](/MongoDB) for the request, and Security below.
536
+ - **Row links.** A plain click opens the deal, Cmd/Ctrl+click or a middle click opens it in a new tab, and Enter on a focused row follows the link. Clicks on buttons, links, menus and editors in a cell never trigger the row. A click on a block in one of the table's slots, such as "Assign to me", runs that block's event and not the table's (the innermost block with actions handles a click, unless an event sets `bubble: true`), and the table still fires its own events for the methods that button calls, such as `onSelectionChange` after `clearSelection`.
537
+ - **Saved views.** The tabs show `views`. A view `id` is a string, a number or a MongoDB ObjectId (`{ _oid }`, matched by its hex, so `id: $_id` works too); this example uses string ids so that Save as can pick one before the request runs. Selecting a tab loads its `view` (parts it leaves out come from `defaultView`) and fires `onViewSelect`. When the current view differs from the tab's, a strip offers Save, Save as and Discard; Save fires `onViewSave` with the tab's `id`, Save as asks for a title (and whether to share it) and fires `onViewSave` without an `id`. A tab's menu offers Delete, which fires `onViewDelete`. The table never stores views itself: update `views` and, for a new view, `activeView`. `locked: true` hides Save and Delete for that tab. Changing the search or collapsing groups never marks a view as changed.
538
+ - **`persist`.** Keeps the user's current view and active tab in `localStorage` under `lowdefy-table:deals`, per app and per signed-in user, so a returning user sees what they left. The view is cleared when the user signs out. A persisted view wins over `activeView` when the page loads.
539
+ - **Bulk actions.** While rows are selected, a bar below the table shows "N selected", "Select all M matching", Clear, and the `bulkActions` slot. Blocks in the toolbar and bulk action slots sit side by side at their content width, like the table's own buttons (set `gap` on the slot, or `layout.flex` on a block, to change that). The blocks in it read `_state: deals_table.selected`, and "Assign to me" sends it to `assign_deals`, one `updateMany` (see below).
540
+ - **Hover buttons.** `showOn: hover` shows the buttons only on the hovered row, or the row focused with the keyboard. They mount only there, which keeps scrolling fast. The event carries `{ row, rowKey, value, button, buttonIndex }`. `applyTransaction` removes the archived row without a full refetch; in server mode a remove also refetches the visible rows.
541
+ - **Inline editing.** Double-click, Enter, F2 or typing on a stage cell opens a select of its `options`. The committed value shows at once with a saving marker while `onCellEdit` runs. If an action fails (a request error, or a `Throw`), the cell reverts and shows the error message. After success the new value shows until the row changes in `data`.
542
+
543
+ **Bulk assign to every matching row.** In server mode most rows are not in the browser, so the header checkbox, and "Select all M matching" in the bulk bar, select every row the view matches as `{ all: true, except, filter, search }`: the view's filter and search, and the keys the user unticked since. Changing the filter or search clears such a selection, so it always describes the rows the user sees. `MongoDBTableChanges` with `selection` (bulk mode) resolves either shape on the server: a key list becomes `{ _id: { $in: [...] } }`, and an all-matching selection is validated and compiled against `queryFields` exactly as `MongoDBTableQuery` compiles the view, with `{ _id: { $nin: except } }`. The base `filter` is one clause of the `updateMany` filter, so a crafted selection can only narrow it, and `set` / `unset` can write only `fields`, never a scope field. The response is `{ matchedCount, modifiedCount }`.
544
+
545
+ `fields` and `queryFields` are different key spaces: `queryFields` are the `MongoDBTableQuery` fields keyed by column key (`owner`, with `path: owner.name`), `fields` are keyed by the field path written (`owner.name`). Keep the query fields in one file and `_ref` it from both requests.
546
+
547
+ To edit more columns, give each one its own request and pick it with the column key: `params: { _string.concat: [update_deal_, { _event: column.key }] }`. Do not build the `$set` field name from the event: the browser could then write any field. Alternatively, save the edit with [MongoDBTableChanges](/MongoDB), which checks the field against its `fields` allowlist and coerces the value to the field type.
548
+
549
+ ### Peek drawer
550
+
551
+ A click opens the row in a drawer; Cmd/Ctrl+click still follows `rowLink`.
552
+
553
+ ```yaml
554
+ - id: deals_table
555
+ type: Table
556
+ properties:
557
+ data:
558
+ _request: deals
559
+ rowLink:
560
+ pageId: deal
561
+ urlQuery:
562
+ _id: _id
563
+ columns:
564
+ - key: name
565
+ title: Deal
566
+ - key: stage
567
+ type: tag
568
+ - key: amount
569
+ type: currency
570
+ events:
571
+ onRowClick:
572
+ - id: set_peek
573
+ type: SetState
574
+ params:
575
+ peek:
576
+ _event: row
577
+ - id: open_peek
578
+ type: CallMethod
579
+ params:
580
+ blockId: peek_drawer
581
+ method: setOpen
582
+ args:
583
+ - open: true
584
+ - id: peek_drawer
585
+ type: Drawer
586
+ properties:
587
+ title:
588
+ _state: peek.name
589
+ blocks:
590
+ - id: peek_amount
591
+ type: Statistic
592
+ properties:
593
+ title: Amount
594
+ value:
595
+ _state: peek.amount
596
+ ```
597
+
598
+ For a page with a [`path`](/page-paths), give its placeholder values in `pathParams`, also as paths in the row: `rowLink: { pageId: ticket, pathParams: { space: space_id, ticket_id: _id } }`. Table links are block properties, so on a public page a link to a protected page with a path cannot be built while the user is logged out (see [`Link`](/Link)).
599
+
600
+ With `onRowClick` defined, a plain click runs it instead of following `rowLink`. `onRowClick` receives `{ row, rowKey, index }`; `index` is the row's position in `data`, whatever the sort (with `tree.childrenField`, in the depth-first list of every row). In server mode it is the row's index in the rows the request matches (inside a group, in the group), and it is `null` for a row that is not in `data`, such as one added with `applyTransaction`.
601
+
602
+ ### Picker
603
+
604
+ Choose rows and read the selection from state. No events needed.
605
+
606
+ ```yaml
607
+ - id: pick_contacts
608
+ type: Table
609
+ properties:
610
+ data:
611
+ _request: contacts
612
+ height: 360
613
+ rowSelection:
614
+ type: checkbox
615
+ preserve: true # keep keys of selected rows that a filter or search hides
616
+ toolbar:
617
+ search: true
618
+ columns:
619
+ - key: name
620
+ type: avatar
621
+ cell:
622
+ nameField: name
623
+ - key: email
624
+ type: email
625
+ - id: add_to_campaign
626
+ type: Button
627
+ properties:
628
+ title:
629
+ _string.concat:
630
+ - 'Add '
631
+ - _array.length:
632
+ _if_none:
633
+ - _state: pick_contacts.selected
634
+ - []
635
+ - ' contacts'
636
+ events:
637
+ onClick:
638
+ - id: add
639
+ type: Request
640
+ params: add_contacts # payload: { ids: { _state: pick_contacts.selected } }
641
+ ```
642
+
643
+ - `type: radio` picks one row; `selected` is then a list of at most one key.
644
+ - Space on a focused row toggles it, and Cmd/Ctrl+C copies the selected rows as tab-separated text.
645
+ - `onSelectionChange` fires with `{ selected, rows }` when the selection changes; `rows` are the selected row objects.
646
+ - "Select all M matching" in the bulk bar writes `{ all: true, except: [], filter, search }` in client mode too: every row matching the view's filter and search, except the unticked keys. Rows that arrive later and match are selected too, and a filter or search change clears the selection. A picker that needs a list of keys can read the selected row objects from `onSelectionChange` `rows`, or handle both shapes.
647
+
648
+ ### Grouped report with totals
649
+
650
+ ```yaml
651
+ - id: sales_report
652
+ type: Table
653
+ properties:
654
+ data:
655
+ _request: sales
656
+ toolbar:
657
+ group: true
658
+ columns: true
659
+ export: true
660
+ defaultView:
661
+ group:
662
+ - key: region
663
+ - key: rep
664
+ aggregates:
665
+ deals: count
666
+ columns:
667
+ - key: region
668
+ groupable: true
669
+ - key: rep
670
+ groupable: true
671
+ - key: deals
672
+ field: name
673
+ title: Deal
674
+ - key: revenue
675
+ type: currency
676
+ aggregate: sum
677
+ - key: margin
678
+ type: percent
679
+ aggregate: avg
680
+ - key: closed
681
+ type: date
682
+ aggregate: latest
683
+ ```
684
+
685
+ - Only columns with `groupable: true` group. The Group toolbar button, the header menu ("Group by this column") and the `setGroup` method set `view.group`.
686
+ - Groups follow the sort on their column, else the column's `options` order, else first appearance. Empty values group as "(Empty)", last.
687
+ - Each group header shows its count and, under their columns, the aggregates in effect: the view's `aggregates` over each column's own `aggregate` (`null` in the view turns a column's default off). The summary footer shows the same aggregates over every filtered row.
688
+ - The current group header sticks to the top while its rows scroll.
689
+ - Collapsed groups are `view.collapsedGroups`, the JSON of the group's value path: `'["EMEA"]'`, `'["EMEA","Ada"]'`, with `null` for empty values. The `expandAllGroups` and `collapseAllGroups` methods open and close every group.
690
+ - A group's checkbox (with `rowSelection`) selects its rows. Space on a group header does the same.
691
+ - `exportCsv` exports every row in the current order, including the rows of collapsed groups. A cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return gets a leading `'`, so a spreadsheet opens it as text rather than running it as a formula (CSV injection); plain numbers such as `-12.5` stay numbers.
692
+
693
+ Aggregates: `sum`, `avg`, `min`, `max`, `count`, `countDistinct`, `countEmpty`, `countNotEmpty`, `percentEmpty` (a fraction), `earliest` and `latest`. In client mode `min` and `max` follow the column's sort order, so they work on text and enum columns too. `MongoDBTableQuery` allows `sum` and `avg` on numeric fields, `min` and `max` on numeric and text fields (text compared by code point unless `options.collation` sets a locale), `earliest` and `latest` on dates, and `countDistinct` only on fields with `groupable: true`.
694
+
695
+ Server mode groups the same way through `MongoDBTableQuery`: the first request returns the groups with their counts and aggregates, and a group's rows load when it is opened. Server groups start collapsed, open one at a time, and have no group checkbox.
696
+
697
+ #### A total row from the request
698
+
699
+ Some totals can not be computed from the rows: a response rate's total is the total responses over the total invited, not the sum or average of the rows' rates. Compute the row in the request and pass it as `summaryRow`:
700
+
701
+ ```yaml
702
+ - id: outcomes
703
+ type: Table
704
+ properties:
705
+ data:
706
+ _request: outcomes.0.rows
707
+ summaryRow:
708
+ _request: outcomes.0.total
709
+ columns:
710
+ - key: region
711
+ - key: invited
712
+ type: number
713
+ - key: rate
714
+ type: percent
715
+ ```
716
+
717
+ - The footer shows the row in place of the aggregates. Each column renders it as it renders a body row, with its `type`, `cell`, `rules` and tooltip; action columns (`buttons`, `menu`) stay empty. Group headers keep their aggregates.
718
+ - It is not a data row. Sorting, filtering, search, selection and the record count leave it out, and it stays in view under `height` like the aggregate footer.
719
+ - `exportCsv` adds it as the last line. In server mode the app writes the file in `onExport`, so the app adds it there.
720
+ - `summary: false` hides it, as it hides the aggregates.
721
+
722
+ ### Tree
723
+
724
+ Rows nested under a parent, with a chevron in the first column.
725
+
726
+ ```yaml
727
+ - id: accounts
728
+ type: Table
729
+ properties:
730
+ data:
731
+ _request: accounts # flat rows with a parent_id
732
+ tree:
733
+ parentField: parent_id # or childrenField: children for nested rows
734
+ rowSelection:
735
+ type: checkbox
736
+ cascade: true # selecting a row selects its descendants
737
+ defaultView:
738
+ sort:
739
+ - key: name
740
+ columns:
741
+ - key: name
742
+ width: 260
743
+ - key: balance
744
+ type: currency
745
+ ```
746
+
747
+ - Give exactly one of `childrenField` (nested rows) or `parentField` (flat rows that name their parent's key). Rows whose parent is not in `data`, and rows in a cycle, are roots.
748
+ - Right expands a row and Left collapses it (or moves to its parent). The expanded row keys are the `expanded` part of the value, so `SetState: { accounts.expanded: [assets] }` opens a row.
749
+ - A sort sorts within each level. A filter or search keeps the ancestors of matching rows.
750
+ - Trees are client mode only, and are never grouped. Rows in a tree cannot be dragged.
751
+
752
+ Load children on demand with `lazy`: a row whose `hasChildrenField` (default `hasChildren`) is true shows a chevron before its children are in `data`, and expanding it fires `onRowExpand { row, rowKey, expanded, needsChildren }`. `needsChildren` is true only when that row is expanded and none of its children are in `data` yet, so skip the load on every other expand and collapse. A row whose request returns no children asks again on its next expand.
753
+
754
+ ```yaml
755
+ - id: folders
756
+ type: Table
757
+ properties:
758
+ data:
759
+ _state: folder_rows
760
+ tree:
761
+ parentField: parent
762
+ lazy: true
763
+ columns:
764
+ - key: name
765
+ events:
766
+ onRowExpand:
767
+ - id: load_children
768
+ type: Request
769
+ params: child_folders # payload: { parent: { _event: rowKey } }
770
+ skip:
771
+ _not:
772
+ _event: needsChildren
773
+ - id: add_children
774
+ type: SetState
775
+ skip:
776
+ _not:
777
+ _event: needsChildren
778
+ params:
779
+ folder_rows:
780
+ _array.concat:
781
+ - _state: folder_rows
782
+ - _request: child_folders
783
+ ```
784
+
785
+ ### Queue
786
+
787
+ A triage list: status tabs with counts, single-key actions, and focus that moves on to the next row after each one.
788
+
789
+ ```yaml
790
+ - id: tickets_queue
791
+ type: Table
792
+ properties:
793
+ data:
794
+ _request: tickets
795
+ height: 520
796
+ keyboard:
797
+ next: true
798
+ toolbar:
799
+ views: true
800
+ search: true
801
+ views:
802
+ - id: open
803
+ title: Open
804
+ locked: true
805
+ count:
806
+ _request: ticket_counts.0.open
807
+ view:
808
+ filter:
809
+ key: status
810
+ op: eq
811
+ value: open
812
+ - id: mine
813
+ title: Assigned to me
814
+ locked: true
815
+ count:
816
+ _request: ticket_counts.0.mine
817
+ view:
818
+ filter:
819
+ and:
820
+ - key: status
821
+ op: eq
822
+ value: open
823
+ - key: assignee
824
+ op: eq
825
+ value:
826
+ $user: id
827
+ user:
828
+ _user: true
829
+ columns:
830
+ - key: subject
831
+ width: 320
832
+ - key: assignee
833
+ field: assignee.id
834
+ hidden: true
835
+ - key: priority
836
+ type: tag
837
+ options: [urgent, high, normal]
838
+ - key: created
839
+ type: datetime
840
+ cell:
841
+ relative: true
842
+ - key: actions
843
+ type: buttons
844
+ title: ''
845
+ width: 190
846
+ sortable: false
847
+ cell:
848
+ buttons:
849
+ - eventName: onAssign
850
+ title: Take (a)
851
+ key: a
852
+ - eventName: onClose
853
+ title: Close (c)
854
+ key: c
855
+ events:
856
+ onAssign:
857
+ - id: assign
858
+ type: Request
859
+ params: assign_ticket # payload: { _id: { _event: rowKey } }
860
+ - id: refetch
861
+ type: Request
862
+ params: [tickets, ticket_counts]
863
+ onClose:
864
+ - id: close
865
+ type: Request
866
+ params: close_ticket
867
+ - id: refetch_closed
868
+ type: Request
869
+ params: [tickets, ticket_counts]
870
+ ```
871
+
872
+ - A button or menu item with `key: a` fires when `a` is pressed on its focused row: the first shown and enabled one with that key, with the same payload as a click. Keys are case-sensitive, and only a bare key counts (no Cmd, Ctrl or Alt). On an editable cell typing opens the editor instead.
873
+ - With `keyboard.next`, focus moves to the row that followed once the event's actions finish, even when the action removed the row from the list. A failed action keeps focus where it was.
874
+ - `count` on a view shows on its tab. The table does not count rows itself: `ticket_counts` is any request that returns the counts.
875
+ - `{ $user: id }` in a filter reads the table's `user` property, set to `{ _user: true }`. In server mode the request resolves `$user` on the server instead (see Security).
876
+
877
+ ### Editable list in a form
878
+
879
+ `TableInput` edits rows that belong to a form. Its value is never the rows, only the changes made to them, so a long list keeps a small state and saves with one request. See [TableInput](/TableInput) for the full value and every editing key.
880
+
881
+ The ingredients of a recipe, stored as an array in the recipe document and ordered by a `position` field:
882
+
883
+ ```yaml
884
+ id: recipe
885
+ type: PageHeaderMenu
886
+ requests:
887
+ - id: get_recipe
888
+ type: MongoDBAggregation
889
+ connectionId: recipes
890
+ payload:
891
+ recipe_id:
892
+ _url_query: id
893
+ properties:
894
+ pipeline:
895
+ - $match:
896
+ _id:
897
+ _payload: recipe_id
898
+ org_id:
899
+ _user: organization.id
900
+ - $project:
901
+ title: 1
902
+ items:
903
+ $sortArray:
904
+ input: $items
905
+ sortBy:
906
+ position: 1
907
+ - id: save_items
908
+ type: MongoDBTableChanges
909
+ connectionId: recipes
910
+ payload:
911
+ recipe_id:
912
+ _url_query: id
913
+ changes:
914
+ _state: items
915
+ properties:
916
+ array:
917
+ documentId:
918
+ _payload: recipe_id
919
+ path: items
920
+ filter:
921
+ org_id:
922
+ _user: organization.id
923
+ positionField: position
924
+ fields:
925
+ ingredient:
926
+ type: text
927
+ qty:
928
+ type: number
929
+ unit:
930
+ type: tag
931
+ changes:
932
+ _payload: changes
933
+ events:
934
+ onMount:
935
+ - id: fetch
936
+ type: Request
937
+ params: get_recipe
938
+ blocks:
939
+ - id: items
940
+ type: TableInput
941
+ properties:
942
+ data:
943
+ _request: get_recipe.0.items
944
+ addRow: true
945
+ addRowText: Add ingredient
946
+ rowDrag:
947
+ positionField: position
948
+ rowActions:
949
+ delete: true
950
+ defaultView:
951
+ sort:
952
+ - key: position
953
+ columns:
954
+ - key: ingredient
955
+ width: 260
956
+ editable: true
957
+ validate:
958
+ - pass:
959
+ op: notEmpty
960
+ message: Name the ingredient.
961
+ - key: qty
962
+ type: number
963
+ width: 110
964
+ editable: true
965
+ default: 1
966
+ - key: unit
967
+ type: tag
968
+ editable: true
969
+ default: g
970
+ options: [g, ml, pcs]
971
+ - id: save
972
+ type: Button
973
+ properties:
974
+ title: Save
975
+ events:
976
+ onClick:
977
+ - id: save_items
978
+ type: Request
979
+ params: save_items
980
+ # Rows the save named but did not find (another user deleted them, or they are outside
981
+ # the filter) are in unmatchedKeys: nothing was written for them.
982
+ - id: check_saved
983
+ type: Throw
984
+ params:
985
+ throw:
986
+ _gt:
987
+ - _array.length:
988
+ _if_none:
989
+ - _request: save_items.unmatchedKeys
990
+ - []
991
+ - 0
992
+ message: Some ingredients were changed or removed by someone else. Reload the recipe and try again.
993
+ - id: refetch
994
+ type: Request
995
+ params: get_recipe
996
+ - id: reset
997
+ type: CallMethod
998
+ params:
999
+ blockId: items
1000
+ method: resetChanges
1001
+ ```
1002
+
1003
+ - Editing a cell writes `updated: { <rowKey>: { <field>: value } }`, only the changed fields; an edit back to the original value drops out. "+ Add ingredient" appends a row with each column's `default` (and a position after the last row) to `added` and opens its first editable cell. Its `rowKey` is always a new temporary key: a `default` on the key column is ignored, so added rows never share a key. The delete button (and Delete or Backspace with `deleteRows: true`) adds the key to `removed`.
1004
+ - `rowDrag.positionField` gives a dragged row one new position (with `pagination`, positions and indices count across every page), the midpoint between its new neighbours, in `moved: { <rowKey>: position }`. A move is one field on one item. Only when two neighbours are closer than 1e-6 is the list renumbered in steps of 1024, which reports every changed position. Dragging is blocked while the table is sorted by anything but the position field ascending, filtered or grouped; the handle says why. Alt+Shift+Up/Down moves the focused row.
1005
+ - In array mode `MongoDBTableChanges` compiles the changes to `$set` with `arrayFilters` on the changed items, `$pull` for removed ones and `$push` for new ones (new items get an ObjectId `_id`). Only the `fields` listed can be written, values are coerced to the field type, and the base `filter` scopes the document.
1006
+ - Treat a non-empty `unmatchedKeys` in the response as a failed save: those rows matched nothing, so nothing was written for them (the rest of the save was). The `Throw` stops the actions and shows the message; the changes stay in the table.
1007
+ - After saving, refetch `data` and call `resetChanges`, which clears the changes and the undo history.
1008
+
1009
+ Collection mode, where every row is a document: leave out `array`. The changes compile to one `bulkWrite` of `updateOne` (the changed dot paths and the position, in one `$set`), `insertOne` and `deleteOne`, each scoped by the base `filter`. The `filter` and `insertDefaults` fields are the rows' scope, and the table can never write them: `fields` that name them are refused, new rows are stamped with the `filter`'s equality conditions (here `org_id`), and a row value can never override an `insertDefaults` value:
1010
+
1011
+ ```yaml
1012
+ - id: save_contacts
1013
+ type: MongoDBTableChanges
1014
+ connectionId: contacts
1015
+ payload:
1016
+ changes:
1017
+ _state: contacts_input
1018
+ properties:
1019
+ filter:
1020
+ org_id:
1021
+ _user: organization.id
1022
+ fields:
1023
+ name:
1024
+ type: text
1025
+ email:
1026
+ type: email
1027
+ role:
1028
+ type: tag
1029
+ insertDefaults: # org_id comes from the filter
1030
+ created:
1031
+ _date: now
1032
+ created_by:
1033
+ _user: id
1034
+ changes:
1035
+ _payload: changes
1036
+ ```
1037
+
1038
+ The `fields` keys are the `TableInput` column `field` paths, the keys of the changes, not the column keys `MongoDBTableQuery` uses. Numeric row keys match in both forms (a key `5` arrives as `"5"` in `updated` and matches a document `_id` of `5` or `"5"`); set `rowKeyType` if a collection holds both as different rows.
1039
+
1040
+ Without a `positionField`, `rowDrag: true` records the full key `order` after a move instead. Array mode applies it by reordering the items on the server; collection mode needs a `positionField` to save an order. The response's `insertedKeys` maps each added row's temporary key to the key it got. See [MongoDBTableChanges](/MongoDB) for the response, row key types and limits.
1041
+
1042
+ ## Columns
1043
+
1044
+ A column is an object, or just its key:
1045
+
1046
+ ```yaml
1047
+ columns:
1048
+ - name # key and field "name", title "Name"
1049
+ - key: owner_name
1050
+ field: owner.name # a dot path into the row
1051
+ title: Owner
1052
+ - key: amount
1053
+ type: currency
1054
+ cell:
1055
+ currency: EUR
1056
+ width: 140
1057
+ aggregate: sum
1058
+ ```
1059
+
1060
+ | Key | Meaning |
1061
+ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1062
+ | `key` | The column id, unique in the table, used in the view, filters, events and `MongoDBTableQuery` `fields`. Defaults to `field`. Two columns showing the same field need their own keys. |
1063
+ | `field` | Dot path of the value in each row. Defaults to `key`. `TableInput` records edits under it, and `MongoDBTableChanges` `fields` are keyed by it. |
1064
+ | `title`, `headerTooltip` | Header text and a header tooltip; both support html. The title defaults to the key in sentence case. |
1065
+ | `type`, `cell` | The cell type (below) and its options. |
1066
+ | `width`, `minWidth`, `maxWidth`, `flex` | Pixels (default width 160, minimum 48). `flex` grows the column into spare width by that weight. |
1067
+ | `align` | `start`, `center` or `end`; number, currency and percent default to `end`. |
1068
+ | `pinned` | `start` or `end`: stays in view while the table scrolls sideways. |
1069
+ | `wrap`, `ellipsis` | Text stays on one line by default. `wrap: true` wraps it, `ellipsis: 2` clamps it to two lines with the full text on hover; both make rows as tall as their content. |
1070
+ | `hidden` | Declared but hidden: users can show it from the column manager. |
1071
+ | `sortable`, `filterable`, `resizable`, `groupable`, `editable` | Per-column switches, defaulting to `defaultColumn` (sortable, filterable and resizable on; groupable and editable off). `editable` also takes `{ when: <condition> }`. |
1072
+ | `searchable` | Include the column in the search. When any column sets it, search reads only those; otherwise every visible column. |
1073
+ | `aggregate` | The column's default aggregate for group headers and the summary footer. |
1074
+ | `options` | Labels and colours for enum values (below). |
1075
+ | `tooltip` | A plain-text hover tooltip: a nunjucks template with `value` and `row`, `{ template }` or `{ field }`. |
1076
+ | `rules` | Conditional formatting (below). |
1077
+ | `validate`, `required`, `default` | Editing: checks before an edit commits, and a `TableInput` new row's value (ignored on the key column, which always gets a new temporary key). |
1078
+ | `children` | Columns grouped under a shared header (the group needs a `title`). |
1079
+ | `collapsible`, `collapsed` | On a group: a chevron in its header collapses and expands it, and `collapsed: true` starts it collapsed (below). |
1080
+ | `showWhen` | In a collapsible group: `open`, `closed` or `always` (the default), when the column or inner group shows (below). |
1081
+
1082
+ `columns` is data, so it can come from a request: `columns: { _request: deal_fields }`. Columns added to config later appear in stored views as hidden, and unknown keys in a stored view are dropped.
1083
+
1084
+ ### Collapsible column groups
1085
+
1086
+ A wide report can open narrow: a group with `collapsible: true` collapses to a summary column and expands to its breakdown columns from the chevron in its header.
1087
+
1088
+ ```yaml
1089
+ columns:
1090
+ - key: project
1091
+ - key: outcomes
1092
+ title: Outcomes
1093
+ collapsible: true
1094
+ collapsed: true
1095
+ children:
1096
+ - key: total
1097
+ type: number
1098
+ showWhen: closed
1099
+ - key: completed
1100
+ type: number
1101
+ - key: opted_out
1102
+ type: number
1103
+ showWhen: open
1104
+ - key: not_reached
1105
+ type: number
1106
+ showWhen: open
1107
+ ```
1108
+
1109
+ - A collapsed group shows its children with `showWhen: closed` or `always`; an expanded one those with `open` or `always`. Here the table opens with Project, Total and Completed, and the chevron swaps Total for Opted out and Not reached.
1110
+ - `showWhen` follows the nearest collapsible group above it. An inner group with `showWhen: open` hides with every column under it while the outer group is collapsed, and can be collapsible itself.
1111
+ - A collapsible group needs a child that shows when it is collapsed, so its header and chevron stay on the table.
1112
+ - The collapsed groups are the view's `collapsedColumnGroups`, by group `key` (without one, `group:<index>`). They are saved and persisted with the view, and `SetState` on it collapses and expands groups.
1113
+ - A column its group hides is not displayed, searched or exported, and stays visible in the view. The column manager lists it as unavailable rather than letting the user tick it on.
1114
+
1115
+ ### Cell types
1116
+
1117
+ The type decides how a value renders, sorts, filters, aggregates, exports and edits.
1118
+
1119
+ | `type` | Shows | `cell` options | Sorts as | Editor |
1120
+ | ------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------- |
1121
+ | `text` | the value (the default) | | text | text input |
1122
+ | `number`, `currency`, `percent` | `Intl.NumberFormat` text; `percent` shows 0.25 as 25% | `format` (`number`, `currency`, `percent`, `compact`), `locale`, `currency` (default `USD`), `currencyDisplay`, `decimals`, `minDecimals`, `maxDecimals`, `notation`, `useGrouping`, `negative` (`parentheses`), `prefix`, `suffix`, `signColor`, `positiveColor`, `negativeColor`, `zeroColor`, `color`, `thresholds` + `colors` | number | number input |
1123
+ | `date`, `datetime` | a dayjs format (default `YYYY-MM-DD` / `YYYY-MM-DD HH:mm`), or relative time with the date on hover | `format`, `relative` | time | date picker |
1124
+ | `boolean` | a label or an icon | `trueLabel`, `falseLabel`, `trueColor`, `falseColor`, `trueIcon`, `falseIcon` | false before true | switch |
1125
+ | `tag`, `status` | a tinted tag, or a dot and a label | `colorMap`, `colorFrom`, `default` | option order, else text | select from `options` |
1126
+ | `tags` | a list of tags: the ones that fit the column whole, then a +N count (`max` caps how many show) | `colorMap`, `colorFrom`, `default`, `max` | text | multi-select from `options` |
1127
+ | `avatar` | initials or an image, and the name; `descriptionField` adds a second line (needs default or comfortable rows)| `nameField`, `srcField`, `idField`, `descriptionField`, `shape`, `link` | text | none |
1128
+ | `people` | overlapping avatars with a +N count | `nameField`, `srcField`, `idField`, `shape`, `max` (default 3) | text | none |
1129
+ | `link` | a link that navigates by itself | `pageId`, `href`, `urlQuery`, `pathParams`, `newTab`, `home`, `back`, `input`, `labelField` | text | none |
1130
+ | `email`, `phone`, `url` | `mailto:`, `tel:` and external links | `label`, `labelField`, `newTab` (url) | text | text input |
1131
+ | `relation` | related records as chips linking to their page | `labelField`, `pageId`, `href`, `urlQuery`, `pathParams`, `newTab` | text | none |
1132
+ | `progress` | a bar | `max` (default 100), `suffix`, `color`, `thresholds`, `colors`, `showValue`, `nullLabel` | number | none |
1133
+ | `rating` | stars | `max`, `color` | number | stars |
1134
+ | `image` | a lazy thumbnail | `width`, `height`, `shape`, `alt`, `altField` | text | none |
1135
+ | `html` | a nunjucks template, or a field holding HTML | `template` | text | none |
1136
+ | `json` | a one-line preview | | its JSON text | none |
1137
+ | `buttons` | row buttons | `buttons`, `showOn` | not sortable | none |
1138
+ | `menu` | a row menu | `items`, `icon`, `title`, `placement` | not sortable | none |
1139
+
1140
+ - Values in `urlQuery`, `pathParams` and every `...Field` option are paths in the row. For `people` they are paths in each person, and for `relation` paths in each related record, where `urlQuery` defaults to `{ _id: _id }` when neither `urlQuery` nor `pathParams` is set.
1141
+ - A `url` value with a scheme other than http or https, such as `javascript:`, shows as text.
1142
+ - An `html` cell's template gets `value` and `row` and is compiled once per column. Values are escaped: use `| safe` to insert HTML held in a field. The output is sanitised, and `data-event` attributes fire block events.
1143
+ - `buttons` and `menu` cells hold no data: they are left out of filters, search and exports. Each button or menu item fires the block event named by its `eventName` with `{ row, rowKey, value, button: { eventName, title }, buttonIndex }` or `{ row, rowKey, value, item: { eventName, title }, itemIndex }`. The keys match the AgGrid buttons and menu cells: `title` / `titleField`, `icon` / `iconField`, `hidden` / `hiddenField`, `disabled` / `disabledField`, `type`, `variant`, `color`, `size`, `shape`, `danger`, `ghost`, `hideTitle`, `tooltip`, `iconPlacement`, and `key` (a single-key shortcut). `hidden` and `disabled` also take `{ when: <condition> }`. An icon-only button shows its title as a tooltip. `showOn: hover` shows the buttons only on the hovered row or the row focused with the keyboard (touch screens always show them).
1144
+ - A `link` cell navigates by itself and also fires `onCellLink { link, row, value }`; do not add a `Link` action to that event.
1145
+
1146
+ ### Options: labels and colours for enum values
1147
+
1148
+ `options` gives the labels and colours of `tag`, `tags` and `status` values, the choices of their filters and editors, and the labels of their group headers and exports. It takes a list of values or `{ value, label, color, icon }`, or a map from value to a label or `{ label, color, icon }`:
1149
+
1150
+ ```yaml
1151
+ - key: stage
1152
+ type: status
1153
+ options:
1154
+ lead: Lead
1155
+ qualified: { label: Qualified, color: processing }
1156
+ won: { label: Won, color: success }
1157
+ lost: { label: Lost, color: error }
1158
+ ```
1159
+
1160
+ Colours are the antd presets (`blue`, `green`, `gold`, ...), the status names (`success`, `processing`, `warning`, `error`) or any CSS colour; the presets and status names follow the theme and dark mode. Enum columns sort and group in option order. A value without an option, in a column without `options` or colour keys, gets a colour picked from the value, so the same value always has the same colour. `options` can come from a global: `options: { _global: enums.deal_stages }`.
1161
+
1162
+ ## Conditions
1163
+
1164
+ One condition language serves filters (`view.filter`, the filter builder, quick filters), `rules`, `rowRules`, `editable.when`, `expandable.rowExpandable.when`, button and menu `hidden` / `disabled`, and `validate`. A condition is a leaf `{ key, op, value }`, or a group `{ and: [...] }` / `{ or: [...] }` of conditions, nested to any depth (the filter builder edits three levels).
1165
+
1166
+ ```yaml
1167
+ filter:
1168
+ and:
1169
+ - { key: stage, op: in, value: [lead, qualified] }
1170
+ - or:
1171
+ - { key: owner, op: eq, value: { $user: id } }
1172
+ - { key: amount, op: gte, value: 10000 }
1173
+ - { key: created, op: within, value: { last: 30, unit: day } }
1174
+ ```
1175
+
1176
+ `key` names a column (its type picks the comparison), or, when no column has that key, a field path in the row. In a column's `rules`, `validate` and `editable.when`, a leaf without `key` tests the column's own value.
1177
+
1178
+ | Operators | For |
1179
+ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
1180
+ | `eq`, `ne`, `in`, `nin`, `empty`, `notEmpty` | every type |
1181
+ | `contains`, `notContains`, `startsWith`, `endsWith` | text, email, phone, url, link, html, relation, tag, status, avatar |
1182
+ | `gt`, `gte`, `lt`, `lte`, `between` (`value: [from, to]`) | number, currency, percent, progress, rating |
1183
+ | `before`, `after`, `between`, `within` | date, datetime |
1184
+ | `isTrue`, `isFalse` | boolean |
1185
+ | `in` (has any of), `nin` (has none of), `contains` (has the value), `eq`, `ne` | tags, people |
1186
+
1187
+ - Text comparisons ignore case. `empty` matches null, a missing value, `''` and `[]`.
1188
+ - Numbers compare as numbers, so numeric strings work.
1189
+ - A `date` column compares whole days: `eq: 2026-03-01` is that day, and `lte: 2026-03-01` includes all of it. A `datetime` column compares the exact instant for `before`, `after` and `between`; `eq` compares the day for both.
1190
+ - `within` takes `{ last: n, unit }` or `{ next: n, unit }` with unit `day`, `week`, `month` or `year`: from the start of the day n units ago to the end of today, or from the start of today to the end of the day n units ahead.
1191
+ - `isFalse` matches every value that is not `true`, including empty values.
1192
+ - Records in a list (`people`, `relation`) compare by `_id`, then `id`, `value`, `name` or `label`, and text operators read their label.
1193
+ - `{ $user: path }` as a value reads the table's `user` property, which blocks need because they do not see the session: set `user: { _user: true }`. A shared saved view with `{ $user: id }` then means "mine" for every user. In server mode the filter goes to the request, which resolves `$user` on the server from its own `user` property.
1194
+
1195
+ ### Conditional formatting
1196
+
1197
+ ```yaml
1198
+ rowRules:
1199
+ - when: { key: overdue, op: isTrue }
1200
+ className: row-overdue
1201
+ columns:
1202
+ - key: score
1203
+ type: number
1204
+ rules:
1205
+ - when: { op: gte, value: 8 }
1206
+ color: success
1207
+ - when: { op: lt, value: 5 }
1208
+ color: error
1209
+ style: { fontWeight: 600 }
1210
+ ```
1211
+
1212
+ Every rule whose `when` holds applies, in order: class names add up, and a later rule's `color` and `style` win. `color` is a text colour (the status names follow the theme). A rule without `when` always applies. Relative dates in rules are resolved when the column config compiles, not re-evaluated as time passes.
1213
+
1214
+ ## The view
1215
+
1216
+ The view is one serialisable object, the `view` part of the value:
1217
+
1218
+ | Key | Holds |
1219
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1220
+ | `columns` | `[{ key, width, pinned, hidden }]` in display order |
1221
+ | `collapsedColumnGroups` | keys of collapsed column groups (`collapsible` groups) |
1222
+ | `sort` | `[{ key, desc }]`, outermost first |
1223
+ | `filter` | a condition, or null |
1224
+ | `search` | the search text: rows match when every word appears (ignoring case) in the display text of the searched columns |
1225
+ | `group` | `[{ key }]` of groupable columns, outermost first |
1226
+ | `collapsedGroups` | keys of collapsed row groups |
1227
+ | `aggregates` | `{ <columnKey>: <fn> \| null }` over the columns' own `aggregate` |
1228
+ | `density` | `compact` (32px rows), `default` (40px) or `comfortable` (52px); starts from `size` |
1229
+ | `wrap` | `true` wraps the text of text-like columns (text, email, phone, url, link, html, relation) without their own `wrap` or `ellipsis`; rows grow to their content. The toolbar density control has a Wrap toggle |
1230
+ | `pageSize` | rows per page with `pagination`; defaults to the `pageSize` property |
1231
+
1232
+ - `defaultView` sets the initial view and the one `Reset` returns to. Each part missing from the value falls back to `defaultView`, then to the column defaults. `defaultView.columns` entries merge over the column config, and columns it leaves out keep their defaults.
1233
+ - While the column layout equals the configured one, the derived view leaves `columns` out, so columns added to config keep appearing until the user changes the layout.
1234
+ - `SetState` on any part loads it: `SetState: { deals.view.sort: [{ key: amount, desc: true }] }`. So do the methods `setFilter`, `clearFilters`, `setSearch` and `setGroup`.
1235
+ - `onChange` fires after the user changes the view or the selection, with `{ value, cause }`; `cause` is `sort`, `filter`, `search`, `columns`, `select`, `group`, `aggregate`, `expand`, `density`, `wrap` (the toolbar Wrap toggle) or `view` (a saved view loaded). It does not fire for `SetState`, `Reset` or the initial value.
1236
+ - To share a view in a link, `persist: { key: view, storage: url }` writes a compact encoding of the view to the `view` query parameter as it changes (with `history.replaceState`), and reads it on load.
1237
+
1238
+ `persist: { key, storage: local }` (the default storage) keeps the view in `localStorage` under `lowdefy-table:<key>`, per app and per signed-in user, and clears it at sign-out or when another user signs in on the browser; a private window or blocked storage just means no persistence. The selection is never persisted. Persisted views outlive config changes (unknown keys are dropped and new columns appended hidden), which is why persistence is opt-in.
1239
+
1240
+ A saved view can carry `wrap` and `pageSize` like any other part: `defaultView: { pageSize: 25 }` or a view tab with `wrap: true`. There is no page size picker; set `view.pageSize` with `SetState` to change it.
1241
+
1242
+ ## Keyboard
1243
+
1244
+ Click a cell, or Tab into the table, and the focused cell shows a ring.
1245
+
1246
+ | Key | Does |
1247
+ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1248
+ | Arrow keys | Move between cells (Up from the first row reaches the header) |
1249
+ | Home / End | First / last cell of the row |
1250
+ | Cmd/Ctrl+Home / End | First / last cell of the table |
1251
+ | PageUp / PageDown | Up or down by a screen of rows |
1252
+ | Enter | On a header: sort (Shift+Enter adds a level). On a row: follow `rowLink` or fire `onRowClick`. On an editable cell: edit. On a group header: open or close it |
1253
+ | Space | Toggle the row's checkbox (or a group's rows, on a group header) |
1254
+ | Right / Left | In a tree or on a group header: expand / collapse |
1255
+ | Enter, F2, or typing | Open the cell editor (typing starts with that character) |
1256
+ | Enter, Tab, Shift+Tab | In an editor: commit (Tab moves to the next editable cell and opens it) |
1257
+ | Esc | In an editor: cancel. In a control inside a cell: back to the cell |
1258
+ | Alt+Shift+Up / Down | Move the focused row (`rowDrag`) |
1259
+ | Alt+Down, Shift+F10, context menu key | Open the focused header's menu |
1260
+ | Cmd/Ctrl+C | Copy the selected rows, or the focused cell, as tab-separated displayed text. A text selection copies as usual |
1261
+ | Cmd/Ctrl+F | Focus the toolbar search (with `toolbar.search`) |
1262
+ | A letter | Fire the row button or menu item with that `key` |
1263
+ | Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z or Ctrl+Y | `TableInput`: undo / redo |
1264
+ | Delete or Backspace | `TableInput` with `deleteRows`: delete the focused row |
1265
+ | Cmd/Ctrl+V | `TableInput`: paste tab-separated text over the cells from the focused one |
1266
+
1267
+ Skeleton rows (loading rows, and server rows not loaded yet) are not cells you can focus: an arrow key onto one moves focus to that row once it loads.
1268
+
1269
+ In the column manager, Alt+Up / Down on a column's handle moves it. `keyboard: false` turns off cell navigation (arrows, Home/End, PageUp/PageDown, Enter and Space on cells), tree Right/Left and `TableInput` paste. Copy, Cmd/Ctrl+F, the header menu keys, the keys of a focused group header, single-key row actions and the editing keys keep working, and the grid roles stay for screen readers.
1270
+
1271
+ ## Performance
1272
+
1273
+ - **Virtualisation.** With `virtual: auto` the table renders only the rows in view once there are more than 200 display rows (groups count), and only the columns in view once there are more than 20 scrolling columns or the table is wider than twice its viewport. Pinned columns always render. Scrolling never re-renders the engine or touches Lowdefy state.
1274
+ - **Fixed heights are fastest.** Rows are one fixed height from the density (32, 40 or 52px) or `rowHeight`. A column with `wrap: true` or `ellipsis` above 1 makes rows as tall as their content: heights are measured as rows render, and column virtualisation turns off, since a row's height then depends on every cell in it. Expandable detail rows are measured too.
1275
+ - **Rich cells.** Hover buttons mount only on the hovered row or the row focused with the keyboard. During a fast scroll, avatar, tag, button and other rich cells show their text and upgrade when the scroll settles. Templates compile once per column, and the template compiler (about 36 kB gzipped) loads only for a table with an `html` template, a template tooltip or `expandable`.
1276
+ - **Data updates.** Rows are compared by key, so a refetch re-renders only rows whose content changed. `rowVersionField`, a dot path such as `updated.timestamp`, compares rows by key and that field instead of by content; a row without the field is compared by content. `applyTransaction` adds, updates or removes rows without replacing `data`.
1277
+ - **Big client data.** Sort, filter and group of 100k rows stay under the 60fps budget in the benchmark (text sort keys and the first search are built in time slices, without blocking). Keep `data` a plain request result: an `_js` or `_function` in it runs on every page update.
1278
+ - **Server mode** is for data the browser should not hold. `blockSize` (default 200) sets the rows per request and `maxBlocks` (default 20) the blocks kept; loads wait for a fast scroll to settle.
1279
+ - **TableLight renders every row** with antd's Table: keep it to hundreds of rows. It logs a development warning above 1,000.
1280
+
1281
+ ## Server mode security
1282
+
1283
+ In server mode the browser sends the view, and the view is user input. `MongoDBTableQuery` is built so that it can only narrow what the base query allows:
1284
+
1285
+ - **The allowlist.** Only keys in `fields` can be sorted, filtered, searched, grouped or aggregated, only with the operators and aggregates their `type` allows, and only with values of that type. Anything else is refused before the query runs. Regex input is escaped, and the view can not send `$where`, `$expr` or pipeline stages.
1286
+ - **The base pipeline runs first.** Put tenant, ownership and permission scoping in `pipeline`, evaluated on the server with `_user`, never in the payload. On a tenant connection the tenant scope comes before it.
1287
+ - **Only allowed fields leave the server.** With `project: true` (the default) each row returns only `_id`, the `fields` paths and the `returnFields` paths, even when the documents hold more. List in `returnFields` the paths cells read without a field of their own: an avatar `srcField`, a link or relation `labelField`, a `rowKey` other than `_id`. `project: false` returns what the base pipeline leaves, for a pipeline that ends in its own `$project`.
1288
+ - **`user: { _user: true }`** on the request resolves `{ $user: path }` filter values on the server from the session. A browser-sent user value is never used, and a missing one throws instead of matching empty fields.
1289
+ - **Bounded requests.** One view may have at most 200 filter conditions and groups (nested at most 8 deep), 1000 filter values in all (500 per `in` / `nin`), strings of at most 200 characters, 10 sort keys and 5 group levels, and a request returns at most `maxRows` (default 1000) rows or groups. The aggregation stops after `options.maxTimeMS`, 10 seconds by default. A request over a limit throws before it runs.
1290
+ - **Selections.** An all-matching selection `{ all: true, except, filter, search }` is not a list of keys. `MongoDBTableChanges` with `selection` recomputes the set on the server: its filter and search are validated against `queryFields` like a view, and the base `filter` is ANDed in, so a crafted selection can not widen a bulk action beyond what the user can read.
1291
+ - **Saves.** `MongoDBTableChanges` writes only the `fields` listed, at their paths, with coerced values, scoped by its base `filter`; row keys and values that are operator objects are refused. Fields that overlap a `filter` or `insertDefaults` field are refused, so a save can not move a row out of scope, and new rows are stamped with the `filter`'s equalities.
1292
+
1293
+ Every column the user can sort or filter must be in `fields`, or the request fails when they try. Set `sortable: false` and `filterable: false` on columns the request does not allow, and give `toolbar.search` only to tables whose request has `search: true` fields. Server search matches the raw field values, not the display labels a client-side search reads.
1294
+
1295
+ **Time zones and indexes.** The browser compares date filters by the user's local days, the server by the days of the request's `timezone` (UTC by default): pass the user's time zone, as `deals_page` does. The request sorts before it pages, so an index on the base match, filter and sort fields (for example `{ org_id: 1, updated: -1, _id: 1 }`) serves each block; without one, MongoDB sorts every matching document for every block. Add indexes for the sorts a large table offers.
1296
+
1297
+ ## Enrichment tables
1298
+
1299
+ Enrichment tables compute columns from other columns, per row: an `enrichment` column calls a provider (an API endpoint of the app), an `ai` column runs a prompt, a `formula` column fills a template in the browser, and an `extract` column reads a value out of another column's result. Users add columns and rows at runtime, run a column, a row or a selection, and open a cell to see its raw result. The run queue lives in the rows, in MongoDB: see [MongoDB enrichment run queue](/MongoDB) for the three requests and the worker endpoint.
1300
+
1301
+ ```yaml
1302
+ - id: leads_table
1303
+ type: Table
1304
+ properties:
1305
+ providers: # the catalogue the add-column picker offers; each maps to enrich_<id>
1306
+ _ref: leads/providers.yaml
1307
+ addColumn: true # the "+" header and its picker
1308
+ addRow: true # "+ New row"
1309
+ importCsv: true # the toolbar's Import button: CSV files of at most 50 MB and 100,000 rows
1310
+ inputFieldPrefix: values # user input columns keep their values at values.<key>
1311
+ columns:
1312
+ _request: get_columns # declared and user-defined columns, merged on the server
1313
+ data:
1314
+ _request: leads
1315
+ ```
1316
+
1317
+ The enrichment feature loads in its own chunk, only for tables that use it (an enrichment, ai, extract, `status` or user-defined column, `providers`, `addColumn`, `addRow` or `importCsv`). Formula columns alone do not load it.
1318
+
1319
+ **Column kinds.** An `ai` column takes `prompt`, `inputs` (every column the prompt uses), `provider` (default `ai`, the app's `enrich_ai` endpoint) and `output: { type, options? }`: the answer is `text`, `number`, `boolean`, `tag` or `tags`, and `tag` and `tags` take `options`, the answers allowed, each its text or `{ value, color }` (the picker shows the options as chips in one field, each starting on a distinct tone, with a colour button of preset tones and a remove button; a user-defined column's option colours are tone names, never CSS values, since they are painted in every viewer's browser). A user-defined column's options without a colour (plain strings written through an API, or a column saved before options had colours) get the tones the picker would give them, in option order, so they look like a picker-made column; a declared column's options without a colour stay neutral, as the config author wrote them. An `enrichment` column takes a `provider` from `providers`, `inputs` mapped to columns or literal values, and `output`, the path of its value in the provider result. A catalogue provider with id `ai` is the AI kind's provider: the picker shows it once, as the AI entry.
1320
+
1321
+ **Inputs read stored values.** An enrichment or ai column's inputs (and an AI prompt's placeholders) read input and data columns (fields the server can read) or other enrichment and ai columns (their result, once done). Formula and extract columns compute in the browser and are never stored, so the server can not send them to a provider: the picker does not offer them, and a column that reads one is refused (a declared column is a config error, a user-defined one an error column). To send a combined value to a provider, map each part as an input; to read a nested result, map the enrichment column itself and pick the path in your provider endpoint. A formula template can read any column.
1322
+
1323
+ **Templates are placeholders.** Formula templates and AI prompts only take `{{ column }}` placeholders (a column key or a dot path), filled in as plain text. They are user content shared between users, and a template engine would run them as code, so the Table refuses tags (`{% %}`), comments (`{# #}`) and expressions (`{{ name | upper }}`), and so should the endpoint that saves a column. Fill prompts on the server with plain string replacement, never `_nunjucks`. A placeholder is `{{ key }}` or `{{ key.path }}` (a dot path into that column's or input's value), optionally with whitespace control (`{{- key -}}`); a key starts with a letter, `_` or `$` and may hold `-`, but not end with one. The server that fills prompts must accept exactly the placeholders the Table does, with the same pattern, so no placeholder the Table accepts is left unfilled (the reference app's `check_column` and `enrich_ai` use it).
1324
+
1325
+ **User-defined columns.** Columns with `userDefined: true` get Rename, Edit, Duplicate, Insert and Delete in their header menu (each shown when the table has the event it fires). A user-defined column whose config is invalid (an unknown provider or answer type, an input column that was deleted) renders as an error column instead of breaking the table: its cells show "Invalid column: <reason>", its header is marked, and its menu offers Edit column and Delete column. A declared column with an invalid config is a config error.
1326
+
1327
+ A user-defined column is one user's content rendered in every viewer's browser, so the Table only takes text-safe config from it: its type must be one of `text`, `email`, `phone`, `url`, `number`, `currency`, `percent`, `progress`, `rating`, `date`, `datetime`, `boolean`, `tag`, `tags`, `status` or `json` (an `html`, `image`, `avatar`, `people`, `link`, `relation` or action type makes it an error column; with no type it is `text`, whatever `defaultColumn` sets), and its `cell`, `rules`, `validate` and template tooltips are ignored (a `{ field }` tooltip is kept). The add-column picker offers only these types. Check stored columns against the same list on the server, as the reference app's column check does.
1328
+
1329
+ **CSV import.** The Import button parses the file in the browser and suggests a column for each header: one whose key or title matches it (ignoring case, spaces and punctuation), then a common synonym ("Website" or "URL" for a domain column, "Employer" or "Organisation" for a company, "Role" for a job title, "Full name" for a name, "E-mail" for email), then a close spelling. Suggestions that are not a column's own name are marked until the user picks another column, and headers without a match become new text columns.
1330
+
1331
+ **Values at field paths.** `onRowAdd` `values` and `onImport` `rows` carry every value at its column's `field` path. New input columns from the picker or a CSV import carry their `field` too, under `inputFieldPrefix` (`values.notes` with `inputFieldPrefix: values`), so the endpoint that stores them only has to accept the paths of its `fields` allowlist. Build that allowlist on the server, with the user input columns added:
1332
+
1333
+ ```yaml
1334
+ fields:
1335
+ _js:
1336
+ fn: |
1337
+ const fields = { ...args.declared };
1338
+ args.columns
1339
+ .filter((column) => column.userDefined === true && column.kind === 'input')
1340
+ .forEach((column) => {
1341
+ fields[column.key] = { type: column.type ?? 'text', path: `values.${column.key}` };
1342
+ });
1343
+ return fields;
1344
+ args:
1345
+ declared:
1346
+ _ref: leads/fields.yaml
1347
+ columns:
1348
+ _step: load_columns
1349
+ ```
1350
+
1351
+ **New rows.** "+ New row" fires `onRowAdd { rowKey, values }`, and the row shows at the end of the table, saving, under `rowKey`, a new random UUID. Insert the row under that key (as its `_id`, or at the field the Table's `rowKey` property names) and the saved row takes the saving row's place the moment it reaches `data`, from a live push or a refetch, even before the event ends. A row stored under a key of its own (a generated ObjectId) shows beside the saving row until the event ends. An app that uses `rowKey` should key every row with a UUID `_id`, imported rows too (`_uuid: true`), and leave `rowKeyType` on MongoDBEnrichmentEnqueue and MongoDBTableChanges at its default, `auto` (`objectId` refuses UUID keys). UUIDs carry no order, so sort the rows by a creation time, with a tiebreak for rows inserted together (their position in an import batch), and index those fields. The key comes from the browser: check its format on the server, and only ever insert with it (`MongoDBInsertOne`, `MongoDBInsertMany`), never an upsert, replace or update keyed by it, so a key that is taken fails the insert instead of overwriting another user's or tenant's row.
1352
+
1353
+ **Read columns on the server.** Endpoints that enqueue runs or run the worker read the table's columns themselves (declared columns plus the stored user columns), never from the event payload: a browser can send any column config. Check every user column when it is saved (its key, provider, inputs, prompt and template), as the enrichment reference app's column check does.
1354
+
1355
+ **Errors users can read.** A cell's `error` is shown to every user of the table: in the cell's tooltip ("Failed after 3 attempts" and the message, shortened) and whole in the details panel. Store messages a user can act on, not the error a connection threw, which names the app's connection and carries the service's response (`company_api: Server returned error 500...`). In the worker's `:catch` and in provider endpoints, map a thrown error to its status (`Provider error (500)`, `Rate limited by the provider (429)`, `The provider did not respond`) and leave the full error to the server log, as the reference app's `run_cell` and `enrich_company_lookup` do.
1356
+
1357
+ **Loading.** Wire `loading` to the rows request (`_request_details: leads.0.loading`) and reload columns and rows with `holdValue: true` after a column or row change, so the table keeps its rows and columns on screen while they reload; the first load shows the table's skeleton rows. The picker, details panel and import dialog open at once, with a spinner while their code loads.
1358
+
1359
+ **Live results.** Push cell updates to the table with `applyTransaction({ update })` from a websocket (`MongoDBChangeStream` on the rows) that sends each changed row's `fullDocument` (projected to the fields the table shows, `_enrich` whole). The default shallow merge replaces each top-level field, so a cell whose rerun found nothing loses its old `value`, `raw` and `inputHash`, as the server unset them. Keep `merge: 'deep'` for partial patches you build yourself: a deep merge never removes a key, so a formula, an extract column or the stale marker would keep reading what the server removed.
1360
+
1361
+ ## Moving from TableLight or AgGrid
1362
+
1363
+ - **From TableLight:** change `type: TableLight` to `type: Table`. Every property keeps its meaning; set `pagination: true` if you relied on TableLight's automatic pager.
1364
+ - **From AgGrid:** move column config by hand. `field` stays `field`, `headerName` becomes `title`, `cell.type` becomes the column's `type` and the rest of `cell` stays. Row events carry `{ row, rowKey, index }`, and button and menu events the same payloads as AgGrid's button and menu cells. A total row in `pinnedBottomRowData` becomes `summaryRow`. `AgGridInput*` holds the rows as its value; `TableInput` holds the changes, saved with `MongoDBTableChanges`.
1365
+
1366
+ ```yaml
1367
+ - id: deals_basic
1368
+ type: Table
1369
+ properties:
1370
+ columns:
1371
+ - key: name
1372
+ title: Deal
1373
+ width: 220
1374
+ - key: stage
1375
+ - key: owner
1376
+ - key: amount
1377
+ type: number
1378
+ data:
1379
+ - _id: d1
1380
+ name: Acme renewal
1381
+ stage: proposal
1382
+ owner: Ada
1383
+ amount: 12000
1384
+ - _id: d2
1385
+ name: Globex expansion
1386
+ stage: qualified
1387
+ owner: Grace
1388
+ amount: 48000
1389
+ - _id: d3
1390
+ name: Initech pilot
1391
+ stage: lead
1392
+ owner: Alan
1393
+ amount: 3500
1394
+ ```
1395
+
1396
+ ```yaml
1397
+ - id: deals_typed
1398
+ type: Table
1399
+ properties:
1400
+ columns:
1401
+ - key: name
1402
+ title: Deal
1403
+ width: 200
1404
+ pinned: start
1405
+ - key: stage
1406
+ type: status
1407
+ options:
1408
+ lead: Lead
1409
+ qualified:
1410
+ label: Qualified
1411
+ color: processing
1412
+ won:
1413
+ label: Won
1414
+ color: success
1415
+ lost:
1416
+ label: Lost
1417
+ color: error
1418
+ - key: owner
1419
+ type: avatar
1420
+ cell:
1421
+ nameField: owner
1422
+ - key: amount
1423
+ type: currency
1424
+ cell:
1425
+ currency: EUR
1426
+ decimals: 0
1427
+ - key: probability
1428
+ type: progress
1429
+ width: 140
1430
+ - key: labels
1431
+ type: tags
1432
+ options:
1433
+ - value: renewal
1434
+ color: blue
1435
+ - value: strategic
1436
+ color: purple
1437
+ - value: at-risk
1438
+ label: At risk
1439
+ color: red
1440
+ - key: updated
1441
+ type: date
1442
+ cell:
1443
+ format: D MMM YYYY
1444
+ - key: website
1445
+ type: url
1446
+ cell:
1447
+ label: Visit
1448
+ data:
1449
+ - _id: d1
1450
+ name: Acme renewal
1451
+ stage: won
1452
+ owner: Ada Lovelace
1453
+ amount: 12000
1454
+ probability: 100
1455
+ labels:
1456
+ - renewal
1457
+ updated: 2026-09-21
1458
+ website: https://example.com
1459
+ - _id: d2
1460
+ name: Globex expansion
1461
+ stage: qualified
1462
+ owner: Grace Hopper
1463
+ amount: 48000
1464
+ probability: 60
1465
+ labels:
1466
+ - strategic
1467
+ updated: 2026-09-02
1468
+ website: https://example.org
1469
+ - _id: d3
1470
+ name: Initech pilot
1471
+ stage: lead
1472
+ owner: Alan Turing
1473
+ amount: 3500
1474
+ probability: 20
1475
+ labels:
1476
+ - at-risk
1477
+ - renewal
1478
+ updated: 2026-08-15
1479
+ - _id: d4
1480
+ name: Umbrella upsell
1481
+ stage: lost
1482
+ owner: Ada Lovelace
1483
+ amount: 9000
1484
+ probability: 0
1485
+ labels: []
1486
+ updated: 2026-07-30
1487
+ ```
1488
+
1489
+ ```yaml
1490
+ - id: deals_selection
1491
+ type: Table
1492
+ properties:
1493
+ rowSelection:
1494
+ type: checkbox
1495
+ defaultView:
1496
+ sort:
1497
+ - key: amount
1498
+ desc: true
1499
+ density: compact
1500
+ columns:
1501
+ - key: name
1502
+ title: Deal
1503
+ width: 220
1504
+ pinned: start
1505
+ - key: stage
1506
+ - key: owner
1507
+ - key: amount
1508
+ type: number
1509
+ data:
1510
+ - _id: d1
1511
+ name: Acme renewal
1512
+ stage: proposal
1513
+ owner: Ada
1514
+ amount: 12000
1515
+ - _id: d2
1516
+ name: Globex expansion
1517
+ stage: qualified
1518
+ owner: Grace
1519
+ amount: 48000
1520
+ - _id: d3
1521
+ name: Initech pilot
1522
+ stage: lead
1523
+ owner: Alan
1524
+ amount: 3500
1525
+ - id: deals_selected
1526
+ type: Span
1527
+ properties:
1528
+ content:
1529
+ _string.concat:
1530
+ - "Selected: "
1531
+ - _json.stringify:
1532
+ - _state: deals_selection.selected
1533
+ - space: 0
1534
+ ```
1535
+
1536
+ ```yaml
1537
+ - id: contacts_toolbar
1538
+ type: Table
1539
+ properties:
1540
+ toolbar:
1541
+ search: true
1542
+ quickFilters:
1543
+ - status
1544
+ filter: true
1545
+ sort: true
1546
+ columns: true
1547
+ density: true
1548
+ export: true
1549
+ columns:
1550
+ - key: name
1551
+ width: 180
1552
+ - key: email
1553
+ type: email
1554
+ width: 220
1555
+ - key: company
1556
+ - key: status
1557
+ type: tag
1558
+ options:
1559
+ - value: active
1560
+ label: Active
1561
+ color: green
1562
+ - value: churned
1563
+ label: Churned
1564
+ color: red
1565
+ - value: trial
1566
+ label: Trial
1567
+ color: gold
1568
+ - key: signed_up
1569
+ type: date
1570
+ cell:
1571
+ relative: true
1572
+ data:
1573
+ - _id: c1
1574
+ name: Ada Lovelace
1575
+ email: ada@example.com
1576
+ company: Acme
1577
+ status: active
1578
+ signed_up: 2026-01-12
1579
+ - _id: c2
1580
+ name: Grace Hopper
1581
+ email: grace@example.com
1582
+ company: Globex
1583
+ status: trial
1584
+ signed_up: 2026-09-20
1585
+ - _id: c3
1586
+ name: Alan Turing
1587
+ email: alan@example.com
1588
+ company: Initech
1589
+ status: churned
1590
+ signed_up: 2025-06-01
1591
+ - _id: c4
1592
+ name: Katherine Johnson
1593
+ email: katherine@example.com
1594
+ company: Acme
1595
+ status: active
1596
+ signed_up: 2026-04-03
1597
+ slots:
1598
+ toolbarStart:
1599
+ blocks:
1600
+ - id: contacts_toolbar_new
1601
+ type: Button
1602
+ properties:
1603
+ title: New contact
1604
+ icon: add
1605
+ size: small
1606
+ ```
1607
+
1608
+ ```yaml
1609
+ - id: notes_paged
1610
+ type: Table
1611
+ properties:
1612
+ pagination: true
1613
+ defaultView:
1614
+ pageSize: 2
1615
+ wrap: true
1616
+ columns:
1617
+ - key: title
1618
+ width: 160
1619
+ - key: note
1620
+ width: 260
1621
+ data:
1622
+ - _id: n1
1623
+ title: Kick-off
1624
+ note: Agree the scope, the owners of each workstream and the first review date.
1625
+ - _id: n2
1626
+ title: Design review
1627
+ note: Walk through the flows with support and sales before the build starts.
1628
+ - _id: n3
1629
+ title: Launch
1630
+ note: Announce in the changelog and email every customer on the beta list.
1631
+ ```
1632
+
1633
+ ```yaml
1634
+ - id: deals_links
1635
+ type: Table
1636
+ properties:
1637
+ rowLink:
1638
+ pageId: deal
1639
+ urlQuery:
1640
+ _id: _id
1641
+ columns:
1642
+ - key: name
1643
+ title: Deal
1644
+ - key: owner
1645
+ data:
1646
+ - _id: d1
1647
+ name: Acme renewal
1648
+ owner: Ada
1649
+ - _id: d2
1650
+ name: Globex expansion
1651
+ owner: Grace
1652
+ ```
1653
+
1654
+ ```yaml
1655
+ - id: tickets_bulk
1656
+ type: Table
1657
+ properties:
1658
+ rowSelection:
1659
+ type: checkbox
1660
+ columns:
1661
+ - key: subject
1662
+ width: 260
1663
+ - key: requester
1664
+ - key: priority
1665
+ type: tag
1666
+ options:
1667
+ - value: high
1668
+ label: High
1669
+ color: red
1670
+ - value: normal
1671
+ label: Normal
1672
+ color: blue
1673
+ - key: actions
1674
+ type: buttons
1675
+ title: ""
1676
+ width: 96
1677
+ pinned: end
1678
+ sortable: false
1679
+ cell:
1680
+ showOn: hover
1681
+ buttons:
1682
+ - eventName: onReply
1683
+ title: Reply
1684
+ icon: mail
1685
+ hideTitle: true
1686
+ - eventName: onClose
1687
+ title: Close
1688
+ icon: check
1689
+ hideTitle: true
1690
+ data:
1691
+ - _id: t1
1692
+ subject: Cannot export the monthly invoice
1693
+ requester: Ada
1694
+ priority: high
1695
+ - _id: t2
1696
+ subject: How do I add a second address?
1697
+ requester: Grace
1698
+ priority: normal
1699
+ - _id: t3
1700
+ subject: Login link expired
1701
+ requester: Alan
1702
+ priority: normal
1703
+ slots:
1704
+ bulkActions:
1705
+ blocks:
1706
+ - id: tickets_bulk_close
1707
+ type: Button
1708
+ properties:
1709
+ title: Close selected
1710
+ size: small
1711
+ events:
1712
+ onClick:
1713
+ - id: tickets_bulk_record
1714
+ type: SetState
1715
+ params:
1716
+ tickets_bulk_closed:
1717
+ _state: tickets_bulk.selected
1718
+ events:
1719
+ onReply:
1720
+ - id: tickets_bulk_reply
1721
+ type: SetState
1722
+ params:
1723
+ tickets_bulk_last:
1724
+ _string.concat:
1725
+ - "Reply to "
1726
+ - _event: row.requester
1727
+ onClose:
1728
+ - id: tickets_bulk_close_one
1729
+ type: SetState
1730
+ params:
1731
+ tickets_bulk_last:
1732
+ _string.concat:
1733
+ - "Close "
1734
+ - _event: rowKey
1735
+ - id: tickets_bulk_status
1736
+ type: Span
1737
+ properties:
1738
+ content:
1739
+ _string.concat:
1740
+ - "Last action: "
1741
+ - _if_none:
1742
+ - _state: tickets_bulk_last
1743
+ - none
1744
+ - " · Closed: "
1745
+ - _json.stringify:
1746
+ - _if_none:
1747
+ - _state: tickets_bulk_closed
1748
+ - []
1749
+ - space: 0
1750
+ ```
1751
+
1752
+ ```yaml
1753
+ - id: deals_grouped
1754
+ type: Table
1755
+ properties:
1756
+ defaultView:
1757
+ group:
1758
+ - key: region
1759
+ - key: owner
1760
+ columns:
1761
+ - key: name
1762
+ title: Deal
1763
+ width: 220
1764
+ - key: region
1765
+ groupable: true
1766
+ - key: owner
1767
+ groupable: true
1768
+ - key: amount
1769
+ type: number
1770
+ aggregate: sum
1771
+ - key: probability
1772
+ type: percent
1773
+ aggregate: avg
1774
+ data:
1775
+ - _id: d1
1776
+ name: Acme renewal
1777
+ region: EMEA
1778
+ owner: Ada
1779
+ amount: 12000
1780
+ probability: 0.9
1781
+ - _id: d2
1782
+ name: Globex expansion
1783
+ region: EMEA
1784
+ owner: Grace
1785
+ amount: 48000
1786
+ probability: 0.6
1787
+ - _id: d3
1788
+ name: Initech pilot
1789
+ region: AMER
1790
+ owner: Alan
1791
+ amount: 3500
1792
+ probability: 0.2
1793
+ - _id: d4
1794
+ name: Umbrella upsell
1795
+ region: EMEA
1796
+ owner: Ada
1797
+ amount: 9000
1798
+ probability: 0.4
1799
+ ```
1800
+
1801
+ ```yaml
1802
+ - id: response_totals
1803
+ type: Table
1804
+ properties:
1805
+ columns:
1806
+ - key: region
1807
+ - key: invited
1808
+ type: number
1809
+ - key: completed
1810
+ type: number
1811
+ - key: rate
1812
+ title: Response rate
1813
+ type: percent
1814
+ cell:
1815
+ decimals: 1
1816
+ data:
1817
+ - _id: r1
1818
+ region: North
1819
+ invited: 400
1820
+ completed: 120
1821
+ rate: 0.3
1822
+ - _id: r2
1823
+ region: South
1824
+ invited: 100
1825
+ completed: 60
1826
+ rate: 0.6
1827
+ summaryRow:
1828
+ region: Total
1829
+ invited: 500
1830
+ completed: 180
1831
+ rate: 0.36
1832
+ ```
1833
+
1834
+ ```yaml
1835
+ - id: outcomes_groups
1836
+ type: Table
1837
+ properties:
1838
+ columns:
1839
+ - key: region
1840
+ - key: outcomes
1841
+ title: Outcomes
1842
+ collapsible: true
1843
+ collapsed: true
1844
+ children:
1845
+ - key: total
1846
+ type: number
1847
+ showWhen: closed
1848
+ - key: completed
1849
+ type: number
1850
+ - key: refused
1851
+ type: number
1852
+ showWhen: open
1853
+ - key: not_reached
1854
+ type: number
1855
+ showWhen: open
1856
+ data:
1857
+ - _id: r1
1858
+ region: North
1859
+ total: 400
1860
+ completed: 120
1861
+ refused: 80
1862
+ not_reached: 200
1863
+ - _id: r2
1864
+ region: South
1865
+ total: 100
1866
+ completed: 60
1867
+ refused: 10
1868
+ not_reached: 30
1869
+ ```
1870
+
1871
+ ```yaml
1872
+ - id: accounts_tree
1873
+ type: Table
1874
+ properties:
1875
+ tree:
1876
+ parentField: parent
1877
+ rowSelection:
1878
+ type: checkbox
1879
+ cascade: true
1880
+ defaultView:
1881
+ sort:
1882
+ - key: name
1883
+ columns:
1884
+ - key: name
1885
+ title: Account
1886
+ width: 220
1887
+ - key: balance
1888
+ type: currency
1889
+ data:
1890
+ - _id: assets
1891
+ name: Assets
1892
+ balance: 128000
1893
+ - _id: cash
1894
+ name: Cash
1895
+ balance: 28000
1896
+ parent: assets
1897
+ - _id: receivables
1898
+ name: Receivables
1899
+ balance: 100000
1900
+ parent: assets
1901
+ - _id: liabilities
1902
+ name: Liabilities
1903
+ balance: 42000
1904
+ - _id: payables
1905
+ name: Payables
1906
+ balance: 42000
1907
+ parent: liabilities
1908
+ - id: accounts_tree_value
1909
+ type: Span
1910
+ properties:
1911
+ content:
1912
+ _string.concat:
1913
+ - "Expanded: "
1914
+ - _json.stringify:
1915
+ - _state: accounts_tree.expanded
1916
+ - space: 0
1917
+ ```
1918
+
1919
+ ```yaml
1920
+ - id: folders_lazy
1921
+ type: Table
1922
+ properties:
1923
+ tree:
1924
+ parentField: parent
1925
+ lazy: true
1926
+ columns:
1927
+ - key: name
1928
+ title: Folder
1929
+ width: 260
1930
+ data:
1931
+ _if_none:
1932
+ - _state: folders_lazy_rows
1933
+ - []
1934
+ events:
1935
+ onMount:
1936
+ - id: folders_lazy_init
1937
+ type: SetState
1938
+ params:
1939
+ folders_lazy_rows:
1940
+ - _id: invoices
1941
+ name: Invoices
1942
+ hasChildren: true
1943
+ - _id: recipes
1944
+ name: Recipes
1945
+ hasChildren: true
1946
+ onRowExpand:
1947
+ - id: folders_lazy_load
1948
+ type: SetState
1949
+ skip:
1950
+ _not:
1951
+ _event: needsChildren
1952
+ params:
1953
+ folders_lazy_rows:
1954
+ _array.concat:
1955
+ - _state: folders_lazy_rows
1956
+ - - _id:
1957
+ _string.concat:
1958
+ - _event: rowKey
1959
+ - "-2025"
1960
+ name: "2025"
1961
+ parent:
1962
+ _event: rowKey
1963
+ - _id:
1964
+ _string.concat:
1965
+ - _event: rowKey
1966
+ - "-2026"
1967
+ name: "2026"
1968
+ parent:
1969
+ _event: rowKey
1970
+ ```
1971
+
1972
+ ```yaml
1973
+ - id: recipes_expandable
1974
+ type: Table
1975
+ properties:
1976
+ expandable:
1977
+ template: |
1978
+ <div style="padding: 8px 0">
1979
+ <strong>{{ row.name }}</strong>: {{ row.method }}
1980
+ </div>
1981
+ rowExpandable:
1982
+ when:
1983
+ key: method
1984
+ op: notEmpty
1985
+ columns:
1986
+ - key: name
1987
+ title: Recipe
1988
+ width: 200
1989
+ - key: minutes
1990
+ type: number
1991
+ data:
1992
+ - _id: r1
1993
+ name: Sourdough loaf
1994
+ minutes: 1440
1995
+ method: Mix, rest overnight, shape and bake at 250°C.
1996
+ - _id: r2
1997
+ name: Pancakes
1998
+ minutes: 20
1999
+ method: Whisk the batter and fry in a hot pan.
2000
+ - _id: r3
2001
+ name: Toast
2002
+ minutes: 3
2003
+ ```
2004
+
2005
+ ```yaml
2006
+ - id: deals_editing
2007
+ type: Table
2008
+ properties:
2009
+ columns:
2010
+ - key: name
2011
+ title: Deal
2012
+ width: 220
2013
+ editable: true
2014
+ validate:
2015
+ - pass:
2016
+ op: notEmpty
2017
+ message: A deal needs a name.
2018
+ - key: stage
2019
+ type: status
2020
+ editable: true
2021
+ options:
2022
+ lead: Lead
2023
+ won:
2024
+ label: Won
2025
+ color: success
2026
+ lost:
2027
+ label: Lost
2028
+ color: error
2029
+ - key: amount
2030
+ type: currency
2031
+ editable:
2032
+ when:
2033
+ key: stage
2034
+ op: ne
2035
+ value: won
2036
+ - key: close_date
2037
+ type: date
2038
+ editable: true
2039
+ data:
2040
+ - _id: d1
2041
+ name: Acme renewal
2042
+ stage: won
2043
+ amount: 12000
2044
+ close_date: 2026-10-01
2045
+ - _id: d2
2046
+ name: Globex expansion
2047
+ stage: lead
2048
+ amount: 48000
2049
+ close_date: 2026-11-15
2050
+ events:
2051
+ onCellEdit:
2052
+ - id: deals_editing_wait
2053
+ type: Wait
2054
+ params:
2055
+ ms: 600
2056
+ - id: deals_editing_record
2057
+ type: SetState
2058
+ params:
2059
+ deals_editing_last:
2060
+ _string.concat:
2061
+ - _event: rowKey
2062
+ - " "
2063
+ - _event: column.key
2064
+ - " = "
2065
+ - _json.stringify:
2066
+ - _event: value
2067
+ - id: deals_editing_value
2068
+ type: Span
2069
+ properties:
2070
+ content:
2071
+ _string.concat:
2072
+ - "Last edit: "
2073
+ - _if_none:
2074
+ - _state: deals_editing_last
2075
+ - none
2076
+ ```
2077
+
2078
+ ```yaml
2079
+ - id: steps_drag
2080
+ type: Table
2081
+ properties:
2082
+ rowDrag:
2083
+ positionField: position
2084
+ defaultView:
2085
+ sort:
2086
+ - key: position
2087
+ columns:
2088
+ - key: title
2089
+ title: Step
2090
+ - key: position
2091
+ type: number
2092
+ width: 110
2093
+ data:
2094
+ - _id: s1
2095
+ title: Plan
2096
+ position: 1024
2097
+ - _id: s2
2098
+ title: Build
2099
+ position: 2048
2100
+ - _id: s3
2101
+ title: Ship
2102
+ position: 3072
2103
+ events:
2104
+ onRowMove:
2105
+ - id: steps_drag_record
2106
+ type: SetState
2107
+ params:
2108
+ steps_drag_last:
2109
+ rowKey:
2110
+ _event: rowKey
2111
+ position:
2112
+ _event: position
2113
+ - id: steps_drag_value
2114
+ type: Span
2115
+ properties:
2116
+ content:
2117
+ _string.concat:
2118
+ - "Last move: "
2119
+ - _json.stringify:
2120
+ - _if_none:
2121
+ - _state: steps_drag_last
2122
+ - none
2123
+ - space: 0
2124
+ ```
2125
+
2126
+ ```yaml
2127
+ - id: tickets_queue
2128
+ type: Table
2129
+ properties:
2130
+ toolbar:
2131
+ views: true
2132
+ keyboard:
2133
+ next: true
2134
+ views:
2135
+ - id: open
2136
+ title: Open
2137
+ count: 2
2138
+ locked: true
2139
+ view:
2140
+ filter:
2141
+ key: status
2142
+ op: eq
2143
+ value: open
2144
+ - id: waiting
2145
+ title: Waiting
2146
+ count: 1
2147
+ locked: true
2148
+ view:
2149
+ filter:
2150
+ key: status
2151
+ op: eq
2152
+ value: waiting
2153
+ columns:
2154
+ - key: subject
2155
+ width: 260
2156
+ - key: status
2157
+ type: tag
2158
+ options:
2159
+ - open
2160
+ - waiting
2161
+ - key: actions
2162
+ type: buttons
2163
+ title: ""
2164
+ width: 200
2165
+ sortable: false
2166
+ cell:
2167
+ buttons:
2168
+ - eventName: onAssign
2169
+ title: Assign (a)
2170
+ key: a
2171
+ - eventName: onSnooze
2172
+ title: Snooze (s)
2173
+ key: s
2174
+ data:
2175
+ - _id: t1
2176
+ subject: Refund for a double charge
2177
+ status: open
2178
+ - _id: t2
2179
+ subject: Change the billing email
2180
+ status: open
2181
+ - _id: t3
2182
+ subject: Waiting for a screenshot
2183
+ status: waiting
2184
+ events:
2185
+ onAssign:
2186
+ - id: tickets_queue_assign
2187
+ type: SetState
2188
+ params:
2189
+ tickets_queue_last:
2190
+ _string.concat:
2191
+ - "Assigned "
2192
+ - _event: rowKey
2193
+ onSnooze:
2194
+ - id: tickets_queue_snooze
2195
+ type: SetState
2196
+ params:
2197
+ tickets_queue_last:
2198
+ _string.concat:
2199
+ - "Snoozed "
2200
+ - _event: rowKey
2201
+ - id: tickets_queue_value
2202
+ type: Span
2203
+ properties:
2204
+ content:
2205
+ _string.concat:
2206
+ - "Focus a row and press a or s. Last: "
2207
+ - _if_none:
2208
+ - _state: tickets_queue_last
2209
+ - none
2210
+ ```
2211
+
2212
+ ```yaml
2213
+ - id: invoices_rules
2214
+ type: Table
2215
+ properties:
2216
+ rowRules:
2217
+ - when:
2218
+ key: overdue
2219
+ op: isTrue
2220
+ style:
2221
+ fontWeight: 600
2222
+ columns:
2223
+ - key: number
2224
+ title: Invoice
2225
+ - key: total
2226
+ type: currency
2227
+ rules:
2228
+ - when:
2229
+ op: gte
2230
+ value: 10000
2231
+ color: success
2232
+ - key: due
2233
+ type: date
2234
+ rules:
2235
+ - when:
2236
+ key: overdue
2237
+ op: isTrue
2238
+ color: error
2239
+ - key: overdue
2240
+ type: boolean
2241
+ hidden: true
2242
+ data:
2243
+ - _id: i1
2244
+ number: INV-1001
2245
+ total: 12500
2246
+ due: 2026-08-01
2247
+ overdue: true
2248
+ - _id: i2
2249
+ number: INV-1002
2250
+ total: 800
2251
+ due: 2026-10-30
2252
+ overdue: false
2253
+ ```
2254
+
2255
+ ```yaml
2256
+ - id: leads_enrichment
2257
+ type: Table
2258
+ properties:
2259
+ addColumn: true
2260
+ addRow: true
2261
+ importCsv: true
2262
+ rowSelection:
2263
+ type: checkbox
2264
+ providers:
2265
+ - id: findEmail
2266
+ title: Find email
2267
+ description: A work email from a name and a domain.
2268
+ inputs:
2269
+ - key: domain
2270
+ title: Domain
2271
+ required: true
2272
+ - key: name
2273
+ title: Name
2274
+ outputs:
2275
+ - path: email
2276
+ title: Email
2277
+ type: email
2278
+ columns:
2279
+ - key: name
2280
+ kind: input
2281
+ editable: true
2282
+ width: 150
2283
+ - key: domain
2284
+ kind: input
2285
+ editable: true
2286
+ width: 140
2287
+ - key: email
2288
+ kind: enrichment
2289
+ type: email
2290
+ provider: findEmail
2291
+ inputs:
2292
+ domain:
2293
+ column: domain
2294
+ name:
2295
+ column: name
2296
+ output: email
2297
+ width: 200
2298
+ - key: segment
2299
+ kind: ai
2300
+ type: tag
2301
+ prompt: Which market segment is {{ domain }} in?
2302
+ inputs:
2303
+ domain:
2304
+ column: domain
2305
+ output:
2306
+ type: tag
2307
+ options:
2308
+ - smb
2309
+ - mid-market
2310
+ - enterprise
2311
+ userDefined: true
2312
+ width: 140
2313
+ - key: linkedin
2314
+ kind: extract
2315
+ source: email
2316
+ path: profile.linkedin
2317
+ userDefined: true
2318
+ - key: greeting
2319
+ kind: formula
2320
+ template: Hi {{ name }}, about {{ domain }}
2321
+ userDefined: true
2322
+ width: 220
2323
+ data:
2324
+ - _id: l1
2325
+ name: Ada
2326
+ domain: acme.com
2327
+ _enrich:
2328
+ email:
2329
+ status: ok
2330
+ value: ada@acme.com
2331
+ inputHash: 1d27590e6f1c9b
2332
+ raw:
2333
+ email: ada@acme.com
2334
+ profile:
2335
+ linkedin: in/ada
2336
+ segment:
2337
+ status: ok
2338
+ value: enterprise
2339
+ - _id: l2
2340
+ name: Grace
2341
+ domain: globex.com
2342
+ _enrich:
2343
+ email:
2344
+ status: running
2345
+ segment:
2346
+ status: queued
2347
+ - _id: l3
2348
+ name: Alan
2349
+ domain: initech.com
2350
+ _enrich:
2351
+ email:
2352
+ status: queued
2353
+ - _id: l4
2354
+ name: Linus
2355
+ domain: umbrella.com
2356
+ _enrich:
2357
+ email:
2358
+ status: error
2359
+ error: The provider timed out.
2360
+ - _id: l5
2361
+ name: Margaret
2362
+ _enrich:
2363
+ email:
2364
+ status: empty
2365
+ error: "Missing input: domain"
2366
+ - _id: l6
2367
+ name: Ivan
2368
+ domain: hooli.com
2369
+ _enrich:
2370
+ email:
2371
+ status: ok
2372
+ value: ivan@old-domain.com
2373
+ inputHash: 0
2374
+ ```
2375
+
2376
+ | Property | Type | Default | Description |
2377
+ | --- | --- | --- | --- |
2378
+ | `columns` | array \| null | - | The columns, in default order. |
2379
+ | `defaultColumn` | object | - | Defaults applied to every column. |
2380
+ | `defaultColumn.sortable` | boolean | `true` | Sort by clicking the header (Shift+click adds to a multi-sort). Defaults to `defaultColumn.sortable` (true). |
2381
+ | `defaultColumn.filterable` | boolean | `true` | Offer the column in filters: the header menu "Filter…" item and the filter builder. |
2382
+ | `defaultColumn.resizable` | boolean | `true` | Resize the column by dragging the right edge of its header. |
2383
+ | `defaultColumn.groupable` | boolean | `false` | Allow grouping rows by this column (view `group`, the `setGroup` method, the header menu). Default false. |
2384
+ | `defaultColumn.editable` | boolean \| object | `false` | Edit cells of this column: `true`, or `{ when: Condition }` to allow it per row. The editor comes from the type: text, email, phone and url edit as text; number, currency and percent as a number; date and datetime with a date picker; boolean with a switch; tag and status select from `options`; tags select several; rating with stars. Enter, F2, double-click or typing opens it; Enter, Tab or leaving commits; Esc cancels. Table fires onCellEdit; TableInput writes its value. |
2385
+ | `defaultColumn.editable.when` | object | - | Condition tested against the row (and the cell value, for leaves without `key`) that decides whether the cell is editable. |
2386
+ | `defaultColumn.width` | number | - | Column width in pixels. Default 160. |
2387
+ | `defaultColumn.minWidth` | number | - | Minimum width in pixels when resizing. Default 48. |
2388
+ | `defaultColumn.maxWidth` | number | - | Maximum width in pixels when resizing. |
2389
+ | `defaultColumn.ellipsis` | integer \| boolean | - | Clamp the text to this many lines (`true` is one) with an ellipsis; the full text shows on hover. More than one line makes rows as tall as their content. |
2390
+ | `defaultColumn.wrap` | boolean | `false` | Wrap long text; rows grow to fit (measured row heights, which turn column virtualisation off). Text stays on one line by default. |
2391
+ | `data` | array \| object \| null | - | The rows, or `{ mode: server, request, blockSize }` to load rows from a request in blocks as the table scrolls. In server mode the table fires the request with the event `{ startRow, endRow, view: { sort, filter, search, group, aggregates }, groupPath, selected }` (read it in the request `payload` with `_event`) and expects `{ rows, total, groups?, aggregates? }`, the contract of `MongoDBTableQuery`. Sorting, filtering and grouping then run on the server. Rows need a `rowKey`. |
2392
+ | `data.mode` | string | - | Load rows from `request`. Enum: `server`. |
2393
+ | `data.request` | string | - | Id of the request on the page that returns `{ rows, total }`. |
2394
+ | `data.blockSize` | integer | `200` | Rows per request. Blocks load as they scroll into view. |
2395
+ | `data.maxBlocks` | integer | `20` | Blocks kept in the cache; the least recently used are dropped (and refetched when they come back into view). |
2396
+ | `rowKey` | string | - | The row field that identifies each row. Defaults to `_id`, then `id`. Rows with neither get a key per row object, which does not survive a refetch. |
2397
+ | `rowVersionField` | string | - | Dot path to a field that changes whenever a row changes (for example `updated.timestamp`). When set, rows are compared by key and this field instead of by content; a row without it is compared by content. |
2398
+ | `user` | object | - | The user object for `$user` values in filters, `rules`, `rowRules` and button `hidden`/`disabled` conditions, usually `{ _user: true }`. Blocks do not see the session, so conditions read `$user` from this property. |
2399
+ | `defaultView` | object | - | The initial and reset view. Parts missing from the table value fall back to this, then to the column defaults. |
2400
+ | `defaultView.columns` | array | - | Column order, widths, pinning and visibility. |
2401
+ | `defaultView.columns.$.key` | string | - | |
2402
+ | `defaultView.columns.$.width` | number | - | |
2403
+ | `defaultView.columns.$.pinned` | string | - | Pin the column to the start or end, where it stays visible while scrolling. Enum: `start`, `end`. |
2404
+ | `defaultView.columns.$.hidden` | boolean | - | |
2405
+ | `defaultView.collapsedColumnGroups` | array | - | Keys of the collapsed collapsible column groups, over the groups' own `collapsed`. A group's key is its `key`, else `group:<index>` (`group:2.0` for the first group inside the third). |
2406
+ | `defaultView.sort` | array | - | Sort order: `[{ key, desc }]`. |
2407
+ | `defaultView.sort.$.key` | string | - | |
2408
+ | `defaultView.sort.$.desc` | boolean | - | |
2409
+ | `defaultView.filter` | object \| null | - | Filter condition: `{ and: [...] }` / `{ or: [...] }` groups of `{ key, op, value }` leaves. Operators depend on the column type; `{ $user: path }` values read the `user` property. |
2410
+ | `defaultView.search` | string \| null | - | Search text: rows match when every word appears (case-insensitive) in the display text of the searched columns. |
2411
+ | `defaultView.group` | array | - | Group rows by these columns, outermost first: `[{ key }]`. Only columns with `groupable: true` group; groups follow the sort on their column, else option order, else first appearance, and empty values group as "(Empty)" last. |
2412
+ | `defaultView.group.$.key` | string | - | |
2413
+ | `defaultView.collapsedGroups` | array | - | Keys of collapsed groups: the JSON of the group value path, for example `["lead"]` or `["EMEA","Ada"]` (empty values are `null`). |
2414
+ | `defaultView.aggregates` | object | - | Aggregates by column key, for example `{ amount: sum, deals: count }`, over the columns' own `aggregate`. `null` turns a column default off. Group headers show them under their columns. |
2415
+ | `defaultView.density` | string | - | Row density: compact 32px, default 40px, comfortable 52px rows. Defaults to `size`. Enum: `compact`, `default`, `comfortable`. |
2416
+ | `defaultView.wrap` | boolean | - | Wrap the text of text-like columns (text, email, phone, url, link, html, relation) that set no `wrap` or `ellipsis` of their own; rows grow to their content. The toolbar density control has a Wrap toggle. |
2417
+ | `defaultView.pageSize` | integer | - | Rows per page when pagination is on. Defaults to the `pageSize` property. |
2418
+ | `rowSelection` | object | - | Turn on row selection. The selection is the `selected` part of the table value. |
2419
+ | `rowSelection.type` | string | `"checkbox"` | Multiple (checkbox) or single (radio) selection. Enum: `checkbox`, `radio`. |
2420
+ | `rowSelection.preserve` | boolean | `false` | Keep selected keys of rows that leave `data`. Always on in server mode. |
2421
+ | `rowSelection.cascade` | boolean | `false` | In a tree, selecting or clearing a row also selects or clears all its descendants. |
2422
+ | `tree` | object | - | Show rows as a tree (client data only): rows are indented under their parent with an expand chevron in the first column, Right and Left expand and collapse, sorting sorts within each level and a filter keeps the ancestors of matching rows. The expanded row keys are the `expanded` part of the table value. Give exactly one of `childrenField` or `parentField`. |
2423
+ | `tree.childrenField` | string | - | Dot path to each row's child rows (nested data). |
2424
+ | `tree.parentField` | string | - | Dot path to the row key of each row's parent (flat data). Rows whose parent is not in `data` are roots. |
2425
+ | `tree.lazy` | boolean | `false` | Load children on demand: rows whose `hasChildrenField` is true show a chevron before their children are loaded, expanding a row fires `onRowExpand` with `needsChildren: true` until its children are in `data`, and the app adds them (for example a request whose result is merged into the data with `parentField` set). |
2426
+ | `tree.hasChildrenField` | string | `"hasChildren"` | With `lazy`, the field that marks rows with children that are not loaded yet. |
2427
+ | `tree.indent` | number | `20` | Indent per level in pixels. |
2428
+ | `expandable` | object | - | Expandable rows: a chevron in the first column opens a detail row below the row, as high as its content. The expanded row keys are the `expanded` part of the table value. |
2429
+ | `expandable.template` | string | - | Nunjucks HTML for the detail row, rendered with `row` and `rowKey`. Output is escaped: use `\| safe` to insert HTML from a field. The HTML is sanitised. |
2430
+ | `expandable.rowExpandable` | object | - | Which rows can expand. |
2431
+ | `expandable.rowExpandable.when` | object | - | A condition (`{ key, op, value }`, or `and` / `or` lists) tested against the row. |
2432
+ | `rowLink` | object | - | Make rows links. A plain click navigates, Cmd/Ctrl or middle click opens a new tab, and Enter on a focused row follows it. Values in `urlQuery` and `pathParams` are row paths. |
2433
+ | `rowLink.pageId` | string | - | The page to open. |
2434
+ | `rowLink.href` | string | - | A URL to open instead of a page. |
2435
+ | `rowLink.urlQuery` | object | - | Query parameters; each value is a path in the row, like `{ _id: _id }`. |
2436
+ | `rowLink.pathParams` | object | - | Values for the page path's placeholders; each value is a path in the row, like `{ ticket_id: _id }`. |
2437
+ | `rowLink.input` | object | - | Input for the page. |
2438
+ | `rowLink.newTab` | boolean | - | Always open in a new tab. |
2439
+ | `rowRules` | array | - | Conditional row formatting: `[{ when, className, style, color }]`, where `when` conditions name columns by `key`. |
2440
+ | `size` | string | `"default"` | Row density: compact 32px, default 40px, comfortable 52px rows. The view starts at this density (`view.density` overrides it). Enum: `compact`, `default`, `comfortable`. |
2441
+ | `bordered` | boolean | `false` | Draw borders between cells. |
2442
+ | `height` | number \| string | - | A fixed table height (px number or CSS size); the rows scroll under a sticky header and the summary row stays in view. Without it the table grows with its rows up to `maxHeight`. |
2443
+ | `maxHeight` | number \| string | `600` | Maximum height when `height` is not set. |
2444
+ | `rowHeight` | number | - | Row height in pixels. Overrides the density height. |
2445
+ | `virtual` | - | `"auto"` | Virtualise rows and columns. `auto` virtualises rows above 200 and columns above 20 or when the table is wider than twice its viewport. Enum: `auto`, `true`, `false`. |
2446
+ | `stickyHeader` | boolean | `true` | Keep the header visible while the table scrolls. |
2447
+ | `rowDrag` | boolean \| object | - | Reorder rows by dragging a handle in a leading column, or with Alt+Shift+ArrowUp/Down on a focused row. Not available while the table is sorted (except ascending by the position field), filtered or grouped, in a tree or in server mode; the handle is disabled with a tooltip saying why. Table fires onRowMove; TableInput records the move in its value. `true`, or `{ positionField }` for fractional positions. |
2448
+ | `rowDrag.positionField` | string | - | Dot path of a numeric position field the rows are ordered by. A move gives only the moved row a new position: the midpoint of its new neighbours (a neighbour ∓ 1024 at the ends), renumbering the list in steps of 1024 only when there is no room left. |
2449
+ | `headerMenu` | boolean | `true` | Show the column menu button in each header (on hover or focus): sort, filter, pin, freeze, autosize, hide and the column manager. |
2450
+ | `reorderable` | boolean | `true` | Reorder columns by dragging their headers. |
2451
+ | `keyboard` | boolean \| object | `true` | Keyboard navigation between cells. Grid roles stay on when off, and so do Ctrl/Cmd+C copy and the keys of a focused group header. An object turns it on with options. |
2452
+ | `keyboard.next` | boolean | `false` | After a row button, menu item or single-key action completes, move focus to the next row (queue and triage lists). |
2453
+ | `toolbar` | boolean \| object | `false` | The toolbar above the table. `true` turns on every item; an object turns on the listed items. |
2454
+ | `toolbar.views` | boolean | `false` | Saved view tabs (needs `views`), with the unsaved changes strip. |
2455
+ | `toolbar.search` | boolean | `false` | A search box that writes `view.search` (Cmd/Ctrl+F focuses it while the table has focus). |
2456
+ | `toolbar.quickFilters` | array | - | Column keys to show as quick filter chips. Columns with `options` get a checkbox list (an `in` condition); others open the column filter. |
2457
+ | `toolbar.filter` | boolean | `false` | A Filter button that edits the whole `view.filter`. |
2458
+ | `toolbar.sort` | boolean | `false` | A Sort button to add, remove, reorder and flip sort levels. |
2459
+ | `toolbar.group` | boolean | `false` | A Group button to pick and order group levels (groupable columns). |
2460
+ | `toolbar.columns` | boolean | `false` | A Columns button that opens the column manager. |
2461
+ | `toolbar.density` | boolean | `false` | A compact / default / comfortable density toggle, with a Wrap toggle for `view.wrap`. |
2462
+ | `toolbar.export` | boolean | `false` | An Export button that downloads the view as CSV. |
2463
+ | `views` | array \| null | - | Saved views, from any source (often a request). Selecting a tab loads its view; changes show an unsaved changes strip with Save, Save as and Discard. |
2464
+ | `activeView` | string \| number \| object \| null | - | The id of the active saved view (an ObjectId id matches by its hex). Defaults to the first view. Changing it selects that view. |
2465
+ | `persist` | object | - | Keep the user's view between visits. Off by default. The selection is never persisted. |
2466
+ | `persist.key` | string | - | Storage key (localStorage) or query parameter name (url). |
2467
+ | `persist.storage` | string | `"local"` | `local` keeps the view in localStorage, per app and per signed-in user and cleared at sign-out (none in a private window or with blocked storage); `url` writes a compact encoding to the query string, replacing history. Enum: `local`, `url`. |
2468
+ | `emptyText` | string | `"No rows"` | What to show when there are no rows - supports html. |
2469
+ | `loading` | boolean | `false` | Show the loading state: skeleton rows without data, a progress bar with it. |
2470
+ | `pagination` | boolean | `false` | Show the rows in pages of `pageSize` with a pager below the table. Off by default, unlike TableLight: the Table scrolls any number of rows virtually. `true` means what it means on TableLight: pages, with the pager always shown. |
2471
+ | `pageSize` | integer | `50` | Rows per page when `pagination` is on (`view.pageSize` overrides it). |
2472
+ | `providers` | array | - | The enrichment providers columns can call (`kind: enrichment`), the catalogue the add-column picker offers. Each maps, on the server, to the app's `enrich_<id>` endpoint, so a column only calls what the app exposes. |
2473
+ | `providers.$.id` | string | - | The provider id, the column `provider`. |
2474
+ | `providers.$.title` | string | - | The name in the picker. |
2475
+ | `providers.$.description` | string | - | A line under the name in the picker. |
2476
+ | `providers.$.icon` | - | - | An icon for the provider. |
2477
+ | `providers.$.inputs` | array | - | The inputs, `[{ key, title, type, required }]`, mapped to columns or literals in the picker. |
2478
+ | `providers.$.outputs` | array | - | Paths in the result a column can show, `[{ path, title, type }]`; the picker sets the column type from it. |
2479
+ | `providers.$.cost` | number | - | The cost of one call, for the app to show. |
2480
+ | `addColumn` | boolean \| object | - | Show a "+" at the end of the header that opens the add-column picker (onColumnAdd). `true` offers every kind; `{ kinds: [...] }` only those (`input`, `formula`, `enrichment`, `ai`, `extract`). |
2481
+ | `addColumn.kinds` | array | - | The column kinds the picker offers. |
2482
+ | `addRow` | boolean | `false` | Show a "+ New row" row under the table that opens an inline editor for the input columns; Enter adds the row through onRowAdd. |
2483
+ | `addRowText` | string | `"New row"` | Text of the new-row row. |
2484
+ | `inputFieldPrefix` | string | - | Where user-defined input columns added in the picker or by a CSV import keep their values: under this path, then the column key (with `values`, a `notes` column stores at `values.notes`, so a column can never name another field of the row). The column is sent with that `field`, and onRowAdd / onImport values sit at it. Without it, at the key. |
2485
+ | `importCsv` | boolean | `false` | Show an Import button in the toolbar: a CSV file (at most 50 MB and 100,000 rows) is parsed in the browser, in slices so the page stays responsive, its headers mapped to input columns (or new text columns), and the rows sent through onImport in batches of 500. |
2486
+ | `summary` | boolean | `true` | Show the summary footer when `summaryRow` is set or any aggregate is in effect: a column `aggregate`, or one the view sets in `view.aggregates`. `false` hides it. |
2487
+ | `summaryRow` | object \| null | - | A row the app computed, such as a report total from the request, shown in the summary footer in place of the aggregates. Each column renders it like a body row, with its `type`, `cell` and `rules`; action columns stay empty. It is not a data row: sorting, filtering, search, selection and the record count leave it out, and `exportCsv` adds it as the last line (in server mode `onExport` produces the file). Group headers keep their aggregates. |
2488
+
2489
+ | Event | Event Data | Description |
2490
+ | --- | --- | --- |
2491
+ | `onChange` | `{ value, cause }` | Trigger when the table value changes through the table: a sort, a filter or search, a column change (resize, reorder, pin, hide, column manager), or a selection. |
2492
+ | `onSelectionChange` | `{ selected, rows }` | Trigger when the row selection changes. "Select all matching" in the bulk bar (and, in server mode, the header checkbox) selects every row the view matches as `{ all: true, except, filter, search }`: every row matching that filter and search except the `except` keys, so a request can resolve it from the value alone. Changing the filter or search clears such a selection. |
2493
+ | `onRowExpand` | `{ row, rowKey, expanded, needsChildren }` | Trigger when a tree row or an expandable row is expanded or collapsed. With `tree.lazy`, load the row's children here when `needsChildren` is true (skip the load action otherwise) and add them to `data`. |
2494
+ | `onExport` | `{ view, filename, formatted }` | Server mode: trigger when `exportCsv` is called. The browser only holds the loaded blocks, so produce the file from the view, for example with a request and a download action. |
2495
+ | `onRowClick` | `{ row, rowKey, index }` | Trigger when a row is clicked, or activated with Enter. Clicks on buttons, links, menus and `data-event` elements in a cell, and clicks that end a text selection, do not trigger it. With `rowLink`, a plain click runs onRowClick instead of following the link. |
2496
+ | `onRowDoubleClick` | `{ row, rowKey, index }` | Trigger when a row is double clicked. |
2497
+ | `onCellClick` | `{ row, rowKey, column, value }` | Trigger actions when a cell is clicked. Clicks on controls in the cell do not trigger it. |
2498
+ | `onViewSelect` | `{ id }` | Trigger when a saved view tab is selected, after its view loads. |
2499
+ | `onViewSave` | `{ view, id, title, shared }` | Trigger when the user saves the current view: Save (with the active view `id`) or Save as (no `id`, a new view). The app stores views; update `views` (and `activeView`) with the result. |
2500
+ | `onViewDelete` | `{ id }` | Trigger when the user deletes a saved view from its tab menu. |
2501
+ | `onCellEdit` | `{ row, rowKey, column, value, previous }` | Trigger when an edited cell commits. The cell shows the new value with a saving indicator while the event runs. When the actions fail (a Request error or a Throw), the cell reverts and shows the error message. After success the new value shows until the row changes in `data`. Without this event, edits only show in the table. |
2502
+ | `onRowMove` | `{ row, rowKey, fromIndex, toIndex, beforeKey, afterKey, position, positions }` | Trigger when a row is dropped at a new place (`rowDrag`): a drag of its handle, or Alt+Shift+ArrowUp/Down. The rows reorder at once with a saving indicator on the handle while the event runs; when the actions fail the order reverts and the handle shows the error message. After success the new order shows until `data` changes. With `rowDrag.positionField`, save `position` on the moved row (`positions` holds every row whose position changed: normally just this one, all rows when the list had to be renumbered). Without it, save the order from `beforeKey` / `afterKey`. |
2503
+ | `onColumnAdd` | `{ column, position }` | Trigger when a column is added: the add-column picker (`addColumn`), Duplicate or Insert left / right in a user-defined column's header menu, or "Add as column" in the cell details panel. The picker stays open, pending, while the event runs, and shows the error when the actions fail. Store the column and add it to `columns`. |
2504
+ | `onColumnUpdate` | `{ column, previous }` | Trigger when a user-defined column is renamed (inline in its header) or edited (the picker). The rename or picker shows it pending while the event runs and the error when it fails. |
2505
+ | `onColumnDelete` | `{ column }` | Trigger when a user-defined column is deleted from its header menu, after the confirmation. The dialog stays open, pending, while the event runs. |
2506
+ | `onColumnRun` | `{ column, mode, selection }` | Trigger to run an enrichment or ai column: Run in its header menu (all rows, empty cells, errors or stale cells) or "Run selected" in the bulk bar. Enqueue the cells, for example with MongoDBEnrichmentEnqueue; their states then show in the cells. |
2507
+ | `onRowRun` | `{ row, rowKey, columns }` | Trigger when a row's run button is clicked (the trailing column, shown on hover): run every enrichment and ai column of the row. |
2508
+ | `onCellRun` | `{ row, rowKey, column }` | Trigger when one cell is rerun: Rerun in the cell details panel, or the rerun button of a stale cell. |
2509
+ | `onRowAdd` | `{ rowKey, values }` | Trigger when a row is added with "+ New row" (`addRow`). The row shows at the end of the table, marked saving, under `rowKey` while the event runs; after it the row comes from `data` (add it there, for example by refetching). Save the row under `rowKey` (as its `_id`, or at the field the `rowKey` property names): the saved row then replaces the saving one as soon as `data` has it, even while the event still runs; a row saved under another key shows beside the saving row until the event settles. When the actions fail, the row goes and the editor shows the error with the values kept. |
2510
+ | `onImport` | `{ rows, newColumns, batchIndex, batchCount, total }` | Trigger for each batch of rows a CSV import sends (`importCsv`), 500 rows at a time, each awaited before the next; a failed batch stops the import and shows its error. Insert the rows, for example with MongoDBInsertMany, and create `newColumns` once. |
2511
+ | `onCellLink` | `{ link, row, value }` | Triggered when a link, avatar link or relation cell is clicked. The link navigates by itself; this event is for anything else to do. |
2512
+ | `onCellButton` | `{ row, rowKey, value, button, buttonIndex }` | Documentation reference - the event fired is the `eventName` of each button in a `buttons` cell. Define any number of named events on the block, such as `onEdit`. |
2513
+ | `onCellMenuItem` | `{ row, rowKey, value, item, itemIndex }` | Documentation reference - the event fired is the `eventName` of each item in a `menu` cell. |
2514
+
2515
+ | Key | Target |
2516
+ | --- | --- |
2517
+ | `/block` | Outer block wrapper (always available). |
2518
+ | `/element` | The table root element. |
2519
+ | `/header` | The header row group. |
2520
+ | `/row` | Every body row. |
2521
+
2522
+ | Slot | Description |
2523
+ | --- | --- |
2524
+ | `toolbarStart` | Blocks at the start of the toolbar, for example a "New deal" button. Blocks sit side by side at their content width (8px gap, wrapping); the slot's `gap`, `align` and `justify` and a block's `layout.flex` still apply. |
2525
+ | `toolbarEnd` | Blocks at the end of the toolbar, side by side like `toolbarStart`. |
2526
+ | `bulkActions` | Blocks in the bulk action bar, shown while rows are selected, side by side at the end of the bar like `toolbarStart`. |
2527
+ | `empty` | Blocks shown instead of the empty state when there are no rows. |