@lowdefy/docs-content 7.1.0 → 7.3.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 (53) hide show
  1. package/content/actions/login.md +1 -1
  2. package/content/actions/posthoginit.md +1 -1
  3. package/content/adapter-reference/mongodbauthadapter.md +2 -2
  4. package/content/agents/agents-introduction.md +41 -1
  5. package/content/callback-reference/auth0logoutcallback.md +1 -1
  6. package/content/concepts/ai-agent-docs.md +116 -108
  7. package/content/concepts/blocks.md +1 -1
  8. package/content/concepts/connections-and-requests.md +8 -8
  9. package/content/concepts/custom-html.md +1 -1
  10. package/content/concepts/dynamic-page-content.md +26 -15
  11. package/content/concepts/events-and-actions.md +24 -0
  12. package/content/concepts/logger.md +1 -1
  13. package/content/concepts/lowdefy-api.md +81 -14
  14. package/content/concepts/lowdefy-schema.md +11 -0
  15. package/content/concepts/mobile-apps.md +110 -0
  16. package/content/concepts/page-and-app-state.md +2 -2
  17. package/content/concepts/theming.md +1 -1
  18. package/content/connections/axioshttp.md +1 -1
  19. package/content/connections/mongodb.md +22 -6
  20. package/content/controls/reject.md +2 -2
  21. package/content/deployment/vercel.md +1 -1
  22. package/content/display-blocks/aggrid.md +1 -1
  23. package/content/display-blocks/search.md +86 -2
  24. package/content/display-blocks/table.md +154 -9
  25. package/content/input-blocks/ratingslider.md +1 -0
  26. package/content/input-blocks/tableinput.md +12 -4
  27. package/content/input-blocks/tiptapinput.md +3 -2
  28. package/content/input-blocks/tiptapmentioninput.md +3 -2
  29. package/content/migration/v3-to-v4.md +2 -2
  30. package/content/operators/_api.md +11 -9
  31. package/content/operators/_base64.md +2 -2
  32. package/content/operators/_log.md +1 -1
  33. package/content/operators/_ref.md +6 -6
  34. package/content/plugins/plugins-introduction.md +13 -0
  35. package/content/plugins/posthog.md +1 -1
  36. package/content/provider-reference/auth-js-providers.md +2 -2
  37. package/content/provider-reference/openidconnectprovider.md +1 -1
  38. package/content/reference/cli.md +164 -0
  39. package/content/testing/config-tests.md +4 -2
  40. package/content/tutorial/tutorial-create-page.md +1 -1
  41. package/content/tutorial/tutorial-requests-api.md +1 -1
  42. package/content/tutorial/tutorial-requests-sql.md +1 -1
  43. package/content/tutorial/tutorial-start.md +1 -1
  44. package/content/user-authentication/auth-configuration.md +9 -9
  45. package/content/user-authentication/auth-steps.md +6 -4
  46. package/content/user-authentication/organizations.md +68 -1
  47. package/content/user-authentication/protected-pages-apis.md +4 -4
  48. package/content/user-authentication/roles.md +2 -2
  49. package/content/user-authentication/user-object.md +2 -2
  50. package/content/websockets/websocket-publish.md +1 -1
  51. package/content/websockets/websockets-introduction.md +54 -2
  52. package/index.json +74 -59
  53. package/package.json +2 -2
@@ -296,6 +296,62 @@ See the [MiniSearch API docs](https://lucaong.github.io/minisearch/classes/MiniS
296
296
  _event: pageId
297
297
  ```
298
298
 
299
+ ```yaml
300
+ - id: example_search_sections
301
+ type: Search
302
+ properties:
303
+ indexUrl: /search-index.json
304
+ recentResults: true
305
+ recentResultsCount: 4
306
+ footer: Enter to open · mod+Enter to ask
307
+ result:
308
+ title: title
309
+ description: snippet
310
+ category: section
311
+ pageId: pageId
312
+ groups:
313
+ - label: Concepts
314
+ match:
315
+ section: Concepts
316
+ limit: 3
317
+ seeAll:
318
+ label: See all
319
+ pageId: docs-search
320
+ urlQuery:
321
+ q: "{query}"
322
+ - label: Blocks
323
+ match:
324
+ section: Blocks
325
+ limit: 3
326
+ pinned:
327
+ title: "Ask the assistant: {query}"
328
+ icon: Sparkles
329
+ shortcut: mod+enter
330
+ events:
331
+ onSelect:
332
+ - id: navigate
333
+ type: Link
334
+ params:
335
+ pageId:
336
+ _event: pageId
337
+ onSeeAll:
338
+ - id: see_all
339
+ type: Link
340
+ params:
341
+ pageId:
342
+ _event: pageId
343
+ urlQuery:
344
+ _event: urlQuery
345
+ onPinned:
346
+ - id: ask
347
+ type: DisplayMessage
348
+ params:
349
+ content:
350
+ _string.concat:
351
+ - "Ask: "
352
+ - _event: query
353
+ ```
354
+
299
355
  | Property | Type | Default | Description |
300
356
  | --- | --- | --- | --- |
301
357
  | `indexUrl` | string \| array | - | URL or array of URLs to pre-built search index JSON files. |
@@ -322,29 +378,53 @@ See the [MiniSearch API docs](https://lucaong.github.io/minisearch/classes/MiniS
322
378
  | `placeholder` | string | `"Search..."` | Search input placeholder text. |
323
379
  | `shortcut` | string | `"mod+k"` | Keyboard shortcut to open the modal. Renders a shortcut badge on the trigger button (see showShortcut). Use "mod" for Cmd on Mac, Ctrl elsewhere. |
324
380
  | `width` | number | `640` | Modal width in pixels. |
325
- | `maxResults` | number | `20` | Maximum number of results displayed. |
381
+ | `maxResults` | number | `20` | Maximum number of results displayed. When any group sets a `limit`, it instead caps each group that sets none, and "Other". |
326
382
  | `result` | object | - | Maps index fields to result UI slots. |
327
383
  | `result.title` | string | `"title"` | Field name for result title. |
328
384
  | `result.description` | string | - | Field name for result description/snippet. |
329
385
  | `result.category` | string | - | Field name for result grouping category. |
330
- | `result.icon` | string | - | Field name for result icon name. |
386
+ | `result.icon` | string | - | Field name for the result icon. The field holds an icon name, or Icon properties such as `{ name, color }`. Results without it show the document icon. |
331
387
  | `result.pageId` | string | - | Field name for Lowdefy page navigation. |
332
388
  | `result.url` | string | - | Field name for external URL navigation. |
333
389
  | `groups` | array | - | Result grouping definitions. |
334
390
  | `groups.$.label` | string | - | Group display label. |
335
391
  | `groups.$.match` | object | - | Field/value pairs to match results to this group. |
336
392
  | `groups.$.icon` | string | - | Icon for the group header. |
393
+ | `groups.$.limit` | number | - | Number of results shown for the group. The heading then shows the number of matches, and a "See all N" row follows the shown rows when there are more. |
394
+ | `groups.$.seeAll` | object \| string | - | The "See all N" row of a group with a `limit`. An object fires `onSeeAll` with `{ group, count, query, pageId, urlQuery }`; a string is the name of the event to fire instead, with the same payload. |
395
+ | `groups.$.seeAll.label` | string | `"See all"` | Row text before the count. |
396
+ | `groups.$.seeAll.pageId` | string | - | Page id sent in the event, for a Link action. |
397
+ | `groups.$.seeAll.urlQuery` | object | - | Url query sent in the event. `{query}` in a string is replaced by the typed search term. |
398
+ | `pinned` | object | - | An action row kept last in the list while a query is typed. It is selected when nothing matches, reached with the arrow keys, and fires `onPinned` with `{ query }`. |
399
+ | `pinned.title` | string | - | Row text. `{query}` is replaced by the typed search term. |
400
+ | `pinned.icon` | string \| object | `"search"` | Row icon: a semantic name, a Lucide icon name, or properties of an Icon block. |
401
+ | `pinned.icon.name` | string | - | Icon name: a semantic name like `edit`, a Lucide icon name like `Pencil`, or a set-qualified name like `tabler:Pencil`. |
402
+ | `pinned.icon.color` | string | - | Icon color. |
403
+ | `pinned.icon.size` | string \| number | - | Size of the icon. Defaults to `theme.icons.size`. |
404
+ | `pinned.icon.rotate` | number | - | Number of degrees to rotate the icon. |
405
+ | `pinned.icon.spin` | boolean | - | Continuously spin the icon with animation. |
406
+ | `pinned.icon.strokeWidth` | number | - | Stroke width of the icon lines, in pixels of the 24px icon grid. Defaults to `theme.icons.strokeWidth` (2). |
407
+ | `pinned.icon.nonScalingStroke` | boolean | - | Keep the stroke width constant at any icon size. Defaults to `theme.icons.nonScalingStroke`. |
408
+ | `pinned.icon.title` | string | - | Icon hover title for accessibility. An empty string marks the icon as decorative. |
409
+ | `pinned.icon.disableLoadingIcon` | boolean | - | While loading after the icon has been clicked, don't render the loading icon. |
410
+ | `pinned.shortcut` | string | - | Keyboard shortcut that selects the row from any row, such as `mod+enter`. Shown as a badge on the row. |
411
+ | `pinned.event` | string | - | Name of the event to fire instead of `onPinned`. |
412
+ | `footer` | string | - | A line of key hints shown below the results. |
337
413
  | `noResultsMessage` | string | `"No results found."` | Message shown when no results match. |
338
414
  | `highlightMatches` | boolean | `true` | Highlight matched terms in results. |
339
415
  | `recentSearches` | boolean | `true` | Show recent searches when input is empty. |
340
416
  | `recentSearchesKey` | string | `"search"` | localStorage key prefix for recent searches. Recent searches are kept per app and per signed-in user, and cleared at sign-out. |
341
417
  | `recentSearchesCount` | number | `5` | Maximum number of recent searches stored. |
418
+ | `recentResults` | boolean | `false` | Remember the results a person selects and list them when the input is empty, in place of recent searches. Kept per app and per signed-in user, like recent searches, and cleared at sign-out. |
419
+ | `recentResultsCount` | number | `4` | Maximum number of recent results stored and listed. |
342
420
  | `theme` | object | - | Antd design token overrides for the trigger Button, the search Modal and its Input, e.g. `borderRadius`, `colorPrimary`, `colorBgElevated` or `fontSize`. See [antd design tokens](https://ant.design/components/overview#design-token). |
343
421
 
344
422
  | Event | Event Data | Description |
345
423
  | --- | --- | --- |
346
424
  | `onSelect` | `{ query, resultCount }` | Trigger actions when a search result is selected. Result item stored fields are spread into the event object. |
347
425
  | `onSearch` | `{ value, resultCount }` | Trigger actions when the search query changes. |
426
+ | `onPinned` | `{ query }` | Trigger actions when the pinned row is selected, by click, Enter or its shortcut. Fires the event named by `pinned.event` instead when that is set. |
427
+ | `onSeeAll` | `{ group, count, query, pageId, urlQuery }` | Trigger actions when a group's "See all" row is clicked and the group's `seeAll` is an object. When `seeAll` is a string, the event of that name fires instead. |
348
428
  | `onOpen` | \- | Trigger actions when the search modal opens. |
349
429
  | `onClose` | \- | Trigger actions when the search modal closes. |
350
430
 
@@ -359,6 +439,10 @@ See the [MiniSearch API docs](https://lucaong.github.io/minisearch/classes/MiniS
359
439
  | `/results` | The scrollable results list. |
360
440
  | `/group` | A result group container. |
361
441
  | `/groupHeading` | A group heading label. |
442
+ | `/groupCount` | The match count in a group heading (shown when the group has a limit). |
443
+ | `/seeAll` | A group's "See all N" row. |
444
+ | `/pinned` | The pinned last row. |
445
+ | `/footer` | The footer line of key hints. |
362
446
  | `/item` | A result item row. |
363
447
  | `/itemIcon` | The icon in a result item. |
364
448
  | `/itemTitle` | The title in a result item. |
@@ -33,7 +33,7 @@ expanded: [] # the expanded tree rows or detail rows
33
33
 
34
34
  - `_state: deals.selected` is always the selection and `_state: deals.view` always the current view, with no `onChange` wiring.
35
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).
36
+ - Rows come from `data`: a list of rows (client mode), or `{ mode: server, request }` or `{ mode: server, endpoint }` (server mode, below).
37
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
38
 
39
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.
@@ -79,6 +79,30 @@ The table shows what it is doing while data loads, the same way in `Table`, `Tab
79
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
80
  | false | rows | **Ready** |
81
81
 
82
+ **Empty states.** With no rows and no filter or search, blocks in the `empty` slot replace "No rows" (else `emptyText`). When a filter or search hides every row, the table says "No matching rows" and offers _Clear filters_; blocks in the `emptyFiltered` slot replace both, for a view whose filter is the point, such as a saved list, where clearing it would throw the list away:
83
+
84
+ ```yaml
85
+ slots:
86
+ empty:
87
+ blocks:
88
+ - id: no_deals
89
+ type: Paragraph
90
+ properties:
91
+ content: No deals yet.
92
+ emptyFiltered:
93
+ blocks:
94
+ - id: no_matching_deals
95
+ type: Paragraph
96
+ properties:
97
+ content: No deals match this view right now.
98
+ - id: edit_filter
99
+ type: Button
100
+ properties:
101
+ title: Edit filter
102
+ ```
103
+
104
+ The wrapper keeps `data-lf-empty="filtered"` whenever a filter or search hides every row, whichever is shown.
105
+
82
106
  **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
107
 
84
108
  ```yaml
@@ -534,7 +558,8 @@ What each part does:
534
558
 
535
559
  - **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
560
  - **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.
561
+ - **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 table with `onViewSaveAs` actions fires that instead (see below). A tab's menu offers Delete, which fires `onViewDelete`; `viewMenu` replaces it with the app's own items (see below). The table never stores views itself: update `views` and, for a new view, `activeView`. `locked: true` hides Save and disables the default Delete for that tab. Changing the search or collapsing groups never marks a view as changed. On a phone (below 768px, antd's `md` breakpoint) the tabs are one select showing the active view, with its menu and the changed-view strip beside it.
562
+ - **Quick filters.** `quickFilters: [stage]` puts a Stage chip in the toolbar. A column with `options` opens a checkbox list that writes one `in` condition, ANDed with the rest of the filter. A list of more than 8 options has a search box at its top that narrows the list by label as the user types (case-insensitive); ticked options stay listed, and Escape clears the search. A column without `options` opens its column filter.
538
563
  - **`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
564
  - **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
565
  - **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.
@@ -546,6 +571,58 @@ What each part does:
546
571
 
547
572
  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
573
 
574
+ **Your own Save as dialog.** Give the table `onViewSaveAs` actions and Save as fires `onViewSaveAs { view }`, the current view, in place of its title and Shared popover, so saving a new view can ask for more: a unique name, a description, a preview of how many rows it matches. The table shows no popover; the app opens its dialog, stores the view and then updates `views` and `activeView`, as after `onViewSave`. Save (with an `id`) still fires `onViewSave`. Without `onViewSaveAs` actions, Save as works as above.
575
+
576
+ ```yaml
577
+ - id: deals_table
578
+ type: Table
579
+ events:
580
+ onViewSaveAs:
581
+ - id: keep_view
582
+ type: SetState
583
+ params:
584
+ new_view:
585
+ view:
586
+ _event: view
587
+ title: ''
588
+ description: ''
589
+ - id: open_save_view
590
+ type: CallMethod
591
+ params:
592
+ blockId: save_view_modal
593
+ method: toggleOpen
594
+
595
+ - id: save_view_modal
596
+ type: Modal
597
+ properties:
598
+ title: Save view
599
+ events:
600
+ onOk:
601
+ - id: insert_view
602
+ type: Request
603
+ params: insert_view # stores new_view, then refetches views and sets active_view
604
+ blocks:
605
+ - id: new_view.title
606
+ type: TextInput
607
+ required: true
608
+ - id: new_view.description
609
+ type: TextArea
610
+ ```
611
+
612
+ **Your own view tab menu.** `viewMenu` sets the items of the active view tab's menu in place of Delete view, for example when views are archived rather than deleted because other features read them. Each item is `{ key, label?, danger?, confirm? }`; picking one fires `onViewMenu { key, id }` with the view's `id`. `confirm: true` asks "Are you sure?" first, and a string asks that message. `locked` does not disable these items. An empty `viewMenu` hides the menu.
613
+
614
+ ```yaml
615
+ viewMenu:
616
+ - key: rename
617
+ label: Rename
618
+ - key: duplicate
619
+ label: Duplicate
620
+ - key: archive
621
+ label: Archive
622
+ danger: true
623
+ confirm: Archive this view? Lists that use it keep working.
624
+ ```
625
+
549
626
  ### Peek drawer
550
627
 
551
628
  A click opens the row in a drawer; Cmd/Ctrl+click still follows `rowLink`.
@@ -1188,10 +1265,13 @@ filter:
1188
1265
  - Numbers compare as numbers, so numeric strings work.
1189
1266
  - 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
1267
  - `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.
1268
+ - `before` and `after` take a date or the same relative date, resolved each time the filter runs, so a saved view stays true as time passes: `{ key: last_contacted, op: before, value: { last: 3, unit: month } }` reads "before 3 months ago" and keeps rows dated before the start of that day, and `after` with `{ next: 2, unit: week }` keeps rows dated after the end of the day 2 weeks from now. A relative bound compares whole days on `date` and `datetime` columns alike. The filter builder offers Date or Relative for both, and a date column's filter menu picks `within`, `before` or `after` under Relative.
1191
1269
  - `isFalse` matches every value that is not `true`, including empty values.
1192
1270
  - Records in a list (`people`, `relation`) compare by `_id`, then `id`, `value`, `name` or `label`, and text operators read their label.
1193
1271
  - `{ $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
1272
 
1273
+ **The filter in words.** The toolbar's Filter button shows the filter as one sentence in its tooltip, built from the column titles and option labels, for example "Stage is any of Lead or Won and Name contains CX and (Amount greater than 1000 or Owner has me)". Groups past the first level go in brackets, relative dates read "before 3 months ago", `$user` values read "me", and a key that names no column reads "an unknown field, <key>,", so a view whose column was removed is still explained. Conditions still being built are left out. The sentence comes from `describeCondition({ condition, fields })` in `@lowdefy/helpers`, a plain function with no React; `MongoDBTableQuery` returns the same sentence as `sentence` when its `fields` carry the same `title` and `options`.
1274
+
1195
1275
  ### Conditional formatting
1196
1276
 
1197
1277
  ```yaml
@@ -1232,6 +1312,7 @@ The view is one serialisable object, the `view` part of the value:
1232
1312
  - `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
1313
  - 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
1314
  - `SetState` on any part loads it: `SetState: { deals.view.sort: [{ key: amount, desc: true }] }`. So do the methods `setFilter`, `clearFilters`, `setSearch` and `setGroup`.
1315
+ - `openFilter` opens the filter builder from a button elsewhere on the page (a list header's Edit filter, an `emptyFiltered` slot), anchored to the toolbar's Filter button as a click on it does: `CallMethod: { blockId: deals, method: openFilter }`. With `args: [{ key: stage }]` it first adds an empty condition on that filterable column and focuses it. It needs `toolbar.filter`; without it the method logs a warning and does nothing. On a phone (below 768px) the toolbar's filter builder opens as a full-height sheet, with the record count at its foot, instead of a popover.
1235
1316
  - `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
1317
  - 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
1318
 
@@ -1292,6 +1373,56 @@ In server mode the browser sends the view, and the view is user input. `MongoDBT
1292
1373
 
1293
1374
  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
1375
 
1376
+ **Rows from an API endpoint.** When the rows may only be read behind an endpoint's own checks, give `data.endpoint` in place of `data.request`. The table calls the endpoint with `CallAPI`, with the fetch event `{ startRow, endRow, view, groupPath, selected }` as its payload, and reads the routine's response as it reads the request's, `{ rows, total, groups?, aggregates? }`. Give exactly one of `request` and `endpoint`. A response without `rows` and `total` shows the table's own error row.
1377
+
1378
+ ```yaml
1379
+ # The table
1380
+ data:
1381
+ mode: server
1382
+ endpoint: deals-rows
1383
+
1384
+ # api/deals-rows.yaml
1385
+ id: deals-rows
1386
+ type: Api
1387
+ routine:
1388
+ # The endpoint's own checks run first, for example a :reject for a caller without access.
1389
+ - id: deals_page
1390
+ type: MongoDBTableQuery
1391
+ connectionId: deals
1392
+ properties:
1393
+ pipeline:
1394
+ - $match:
1395
+ org_id:
1396
+ _user: organization.id
1397
+ fields:
1398
+ _ref: deals/table_fields.yaml
1399
+ user:
1400
+ _user: true
1401
+ view:
1402
+ _payload: view
1403
+ startRow:
1404
+ _payload: startRow
1405
+ endRow:
1406
+ _payload: endRow
1407
+ groupPath:
1408
+ _payload: groupPath
1409
+ - :return:
1410
+ _step: deals_page
1411
+ ```
1412
+
1413
+ **Fields from the page.** `data.payload` adds fields to every fetch event, beside `startRow`, `view` and the rest, for a filter the page keeps outside the table's view, such as a region picked above the table. Kept out of the view, it never ends up in a saved view's filter. The table's own fields win on a clash, and a changed payload starts the rows again from the top. Read the fields in the request or routine with `_event` or `_payload`, and check them there like any other input.
1414
+
1415
+ ```yaml
1416
+ data:
1417
+ mode: server
1418
+ endpoint: deals-rows
1419
+ payload:
1420
+ region:
1421
+ _state: region
1422
+ ```
1423
+
1424
+ The fetch event carries no time zone, so a routine that filters dates by the user's days sets `timezone` itself, for example from the user's profile.
1425
+
1295
1426
  **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
1427
 
1297
1428
  ## Enrichment tables
@@ -1356,6 +1487,8 @@ fields:
1356
1487
 
1357
1488
  **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
1489
 
1490
+ **Raw results on demand.** A provider's raw answer is often many times the size of the value, and the table only shows it in the details panel. A table can leave it out of its rows (strip `_enrich.<key>.raw` in the rows request) and set `rawEndpoint` to an API endpoint that returns one cell's raw result: the details panel calls it with `{ rowKey, key }` (the row's key and the column key) when it opens a finished enrichment or ai cell whose row carries no `raw`, shows "Loading the raw result…" meanwhile, and calls it again when the cell finishes a new run. The endpoint returns `{ raw }`; scope its read as you scope the rows. Extract columns read the raw result from the row, so keep the fields they read in the rows; a raw result loaded from the endpoint shows without the add-as-column buttons. The reference app's `enrichment_raw_endpoint` page and `leads_cell_raw` endpoint show the pattern.
1491
+
1359
1492
  **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
1493
 
1361
1494
  ## Moving from TableLight or AgGrid
@@ -2388,9 +2521,11 @@ fields:
2388
2521
  | `defaultColumn.maxWidth` | number | - | Maximum width in pixels when resizing. |
2389
2522
  | `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
2523
  | `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`. |
2524
+ | `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`. In place of `request`, `endpoint` names an API endpoint: the table calls it with the event as its payload, and its routine returns the same `{ rows, total }`. `payload` adds the page's own fields to every fetch event. |
2392
2525
  | `data.mode` | string | - | Load rows from `request`. Enum: `server`. |
2393
- | `data.request` | string | - | Id of the request on the page that returns `{ rows, total }`. |
2526
+ | `data.request` | string | - | Id of the request on the page that returns `{ rows, total }`. Give this or `endpoint`. |
2527
+ | `data.endpoint` | string | - | Id of an API endpoint whose routine returns `{ rows, total }`, called with the fetch event as its payload. Give this or `request`; use it for rows a page request may not read, behind the endpoint's own checks. |
2528
+ | `data.payload` | object | - | Fields added to every fetch event, beside `startRow`, `view` and the rest, for a filter the page keeps outside the table's view (a region picked above the table). The table's own fields win on a clash. A change starts the rows again from the top. |
2394
2529
  | `data.blockSize` | integer | `200` | Rows per request. Blocks load as they scroll into view. |
2395
2530
  | `data.maxBlocks` | integer | `20` | Blocks kept in the cache; the least recently used are dropped (and refetched when they come back into view). |
2396
2531
  | `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. |
@@ -2406,7 +2541,7 @@ fields:
2406
2541
  | `defaultView.sort` | array | - | Sort order: `[{ key, desc }]`. |
2407
2542
  | `defaultView.sort.$.key` | string | - | |
2408
2543
  | `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. |
2544
+ | `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. Date `within` takes a relative date `{ last \| next: n, unit: day \| week \| month \| year }`, and `before` and `after` take a date or a relative date, so `{ op: before, value: { last: 3, unit: month } }` keeps meaning "before 3 months ago". |
2410
2545
  | `defaultView.search` | string \| null | - | Search text: rows match when every word appears (case-insensitive) in the display text of the searched columns. |
2411
2546
  | `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
2547
  | `defaultView.group.$.key` | string | - | |
@@ -2419,6 +2554,7 @@ fields:
2419
2554
  | `rowSelection.type` | string | `"checkbox"` | Multiple (checkbox) or single (radio) selection. Enum: `checkbox`, `radio`. |
2420
2555
  | `rowSelection.preserve` | boolean | `false` | Keep selected keys of rows that leave `data`. Always on in server mode. |
2421
2556
  | `rowSelection.cascade` | boolean | `false` | In a tree, selecting or clearing a row also selects or clears all its descendants. |
2557
+ | `rowSelection.selectable` | object | - | A condition (`{ key, op, value }`, or `and` / `or` lists) tested against the row. Rows that fail it have a disabled checkbox, are skipped by the header checkbox and by select-all, and are left out of its checked state. An `{ all: true }` selection lists the rows it rejects in `except`; in server mode those are the loaded rows, and the server resolves the rest. |
2422
2558
  | `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
2559
  | `tree.childrenField` | string | - | Dot path to each row's child rows (nested data). |
2424
2560
  | `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. |
@@ -2453,7 +2589,7 @@ fields:
2453
2589
  | `toolbar` | boolean \| object | `false` | The toolbar above the table. `true` turns on every item; an object turns on the listed items. |
2454
2590
  | `toolbar.views` | boolean | `false` | Saved view tabs (needs `views`), with the unsaved changes strip. |
2455
2591
  | `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. |
2592
+ | `toolbar.quickFilters` | array | - | Column keys to show as quick filter chips. Columns with `options` get a checkbox list (an `in` condition), with a search box over its labels when it has more than 8 options; others open the column filter. |
2457
2593
  | `toolbar.filter` | boolean | `false` | A Filter button that edits the whole `view.filter`. |
2458
2594
  | `toolbar.sort` | boolean | `false` | A Sort button to add, remove, reorder and flip sort levels. |
2459
2595
  | `toolbar.group` | boolean | `false` | A Group button to pick and order group levels (groupable columns). |
@@ -2461,6 +2597,11 @@ fields:
2461
2597
  | `toolbar.density` | boolean | `false` | A compact / default / comfortable density toggle, with a Wrap toggle for `view.wrap`. |
2462
2598
  | `toolbar.export` | boolean | `false` | An Export button that downloads the view as CSV. |
2463
2599
  | `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. |
2600
+ | `viewMenu` | array | - | The items of the active view tab's menu, in place of Delete view: for example Rename, Duplicate and Archive. Clicking one fires `onViewMenu` with its `key` and the view `id`. Without it the menu has Delete view, firing `onViewDelete` (disabled on a `locked` view). |
2601
+ | `viewMenu.$.key` | string | - | The item key `onViewMenu` receives. |
2602
+ | `viewMenu.$.label` | string | - | The item text. Defaults to the key. |
2603
+ | `viewMenu.$.danger` | boolean | - | Show the item in the danger colour. |
2604
+ | `viewMenu.$.confirm` | boolean \| string | - | Ask before firing: `true` asks "Are you sure?", a string asks that message. |
2464
2605
  | `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
2606
  | `persist` | object | - | Keep the user's view between visits. Off by default. The selection is never persisted. |
2466
2607
  | `persist.key` | string | - | Storage key (localStorage) or query parameter name (url). |
@@ -2482,6 +2623,7 @@ fields:
2482
2623
  | `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
2624
  | `addRowText` | string | `"New row"` | Text of the new-row row. |
2484
2625
  | `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. |
2626
+ | `rawEndpoint` | string | - | The id of an API endpoint the details panel calls for a finished enrichment or ai cell's raw result when the row's `_enrich.<key>` carries none, so rows can leave the raw answers out. Its payload is `{ rowKey, key }` (the row's key and the column key); it returns `{ raw }`. |
2485
2627
  | `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
2628
  | `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
2629
  | `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. |
@@ -2496,8 +2638,10 @@ fields:
2496
2638
  | `onRowDoubleClick` | `{ row, rowKey, index }` | Trigger when a row is double clicked. |
2497
2639
  | `onCellClick` | `{ row, rowKey, column, value }` | Trigger actions when a cell is clicked. Clicks on controls in the cell do not trigger it. |
2498
2640
  | `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. |
2641
+ | `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), unless the block has `onViewSaveAs` actions. The app stores views; update `views` (and `activeView`) with the result. |
2642
+ | `onViewSaveAs` | `{ view }` | Trigger when the user clicks Save as, in place of the built-in title and Shared popover, when the block has actions on it. Open your own dialog (for example a modal asking for a name and description), store the view, then update `views` and `activeView` as after `onViewSave`. |
2643
+ | `onViewMenu` | `{ key, id }` | Trigger when the user picks a `viewMenu` item on a saved view tab, after its confirmation when the item has `confirm`. |
2644
+ | `onViewDelete` | `{ id }` | Trigger when the user deletes a saved view from its tab menu (the default menu, without `viewMenu`). |
2501
2645
  | `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
2646
  | `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
2647
  | `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`. |
@@ -2524,4 +2668,5 @@ fields:
2524
2668
  | `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
2669
  | `toolbarEnd` | Blocks at the end of the toolbar, side by side like `toolbarStart`. |
2526
2670
  | `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. |
2671
+ | `empty` | Blocks shown instead of the empty state when there are no rows and no filter or search. |
2672
+ | `emptyFiltered` | Blocks shown instead of "No matching rows" and Clear filters when a filter or search hides every row, for example "No deals match this view right now." with an Edit filter button, so the view keeps its filter. |
@@ -669,6 +669,7 @@ Rating slider with customizable range, icons, and N/A option.
669
669
  | `label.hasFeedback` | boolean | `true` | Display feedback extra from validation, this does not disable validation. |
670
670
  | `label.inline` | boolean | `false` | Render input and label inline. |
671
671
  | `label.wrap` | boolean | `false` | Wrap long label text onto multiple lines when the label is inline. Labels above their input always wrap. |
672
+ | `marks` | object | - | Tick marks on the slider. Keys are slider values and values are labels: a string, or `{ style, label }` as antd takes. Replaces the marks `showMarks` draws, including the blank mark one step below `min`. Example: { 0: "0", 5: "5", 10: "10" }. |
672
673
  | `min` | number | `0` | The minimum value of the slider. |
673
674
  | `max` | number | `10` | The maximum value of the slider. |
674
675
  | `notApplicableLabel` | string | `"N/A"` | Label shown at the null value of the slider. |
@@ -348,7 +348,7 @@ Any other save path works too: the value is plain data, so a request can read `_
348
348
  | `defaultView.sort` | array | - | Sort order: `[{ key, desc }]`. |
349
349
  | `defaultView.sort.$.key` | string | - | |
350
350
  | `defaultView.sort.$.desc` | boolean | - | |
351
- | `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. |
351
+ | `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. Date `within` takes a relative date `{ last \| next: n, unit: day \| week \| month \| year }`, and `before` and `after` take a date or a relative date, so `{ op: before, value: { last: 3, unit: month } }` keeps meaning "before 3 months ago". |
352
352
  | `defaultView.search` | string \| null | - | Search text: rows match when every word appears (case-insensitive) in the display text of the searched columns. |
353
353
  | `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. |
354
354
  | `defaultView.group.$.key` | string | - | |
@@ -361,6 +361,7 @@ Any other save path works too: the value is plain data, so a request can read `_
361
361
  | `rowSelection.type` | string | `"checkbox"` | Multiple (checkbox) or single (radio) selection. Enum: `checkbox`, `radio`. |
362
362
  | `rowSelection.preserve` | boolean | `false` | Keep selected keys of rows that leave `data`. Always on in server mode. |
363
363
  | `rowSelection.cascade` | boolean | `false` | In a tree, selecting or clearing a row also selects or clears all its descendants. |
364
+ | `rowSelection.selectable` | object | - | A condition (`{ key, op, value }`, or `and` / `or` lists) tested against the row. Rows that fail it have a disabled checkbox, are skipped by the header checkbox and by select-all, and are left out of its checked state. An `{ all: true }` selection lists the rows it rejects in `except`; in server mode those are the loaded rows, and the server resolves the rest. |
364
365
  | `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`. |
365
366
  | `tree.childrenField` | string | - | Dot path to each row's child rows (nested data). |
366
367
  | `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. |
@@ -395,7 +396,7 @@ Any other save path works too: the value is plain data, so a request can read `_
395
396
  | `toolbar` | boolean \| object | `false` | The toolbar above the table. `true` turns on every item; an object turns on the listed items. |
396
397
  | `toolbar.views` | boolean | `false` | Saved view tabs (needs `views`), with the unsaved changes strip. |
397
398
  | `toolbar.search` | boolean | `false` | A search box that writes `view.search` (Cmd/Ctrl+F focuses it while the table has focus). |
398
- | `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. |
399
+ | `toolbar.quickFilters` | array | - | Column keys to show as quick filter chips. Columns with `options` get a checkbox list (an `in` condition), with a search box over its labels when it has more than 8 options; others open the column filter. |
399
400
  | `toolbar.filter` | boolean | `false` | A Filter button that edits the whole `view.filter`. |
400
401
  | `toolbar.sort` | boolean | `false` | A Sort button to add, remove, reorder and flip sort levels. |
401
402
  | `toolbar.group` | boolean | `false` | A Group button to pick and order group levels (groupable columns). |
@@ -403,6 +404,11 @@ Any other save path works too: the value is plain data, so a request can read `_
403
404
  | `toolbar.density` | boolean | `false` | A compact / default / comfortable density toggle, with a Wrap toggle for `view.wrap`. |
404
405
  | `toolbar.export` | boolean | `false` | An Export button that downloads the view as CSV. |
405
406
  | `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. |
407
+ | `viewMenu` | array | - | The items of the active view tab's menu, in place of Delete view: for example Rename, Duplicate and Archive. Clicking one fires `onViewMenu` with its `key` and the view `id`. Without it the menu has Delete view, firing `onViewDelete` (disabled on a `locked` view). |
408
+ | `viewMenu.$.key` | string | - | The item key `onViewMenu` receives. |
409
+ | `viewMenu.$.label` | string | - | The item text. Defaults to the key. |
410
+ | `viewMenu.$.danger` | boolean | - | Show the item in the danger colour. |
411
+ | `viewMenu.$.confirm` | boolean \| string | - | Ask before firing: `true` asks "Are you sure?", a string asks that message. |
406
412
  | `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. |
407
413
  | `persist` | object | - | Keep the user's view between visits. Off by default. The selection is never persisted. |
408
414
  | `persist.key` | string | - | Storage key (localStorage) or query parameter name (url). |
@@ -429,8 +435,10 @@ Any other save path works too: the value is plain data, so a request can read `_
429
435
  | `onRowDoubleClick` | `{ row, rowKey, index }` | Trigger when a row is double clicked. |
430
436
  | `onCellClick` | `{ row, rowKey, column, value }` | Trigger actions when a cell is clicked. Clicks on controls in the cell do not trigger it. |
431
437
  | `onViewSelect` | `{ id }` | Trigger when a saved view tab is selected, after its view loads. |
432
- | `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. |
433
- | `onViewDelete` | `{ id }` | Trigger when the user deletes a saved view from its tab menu. |
438
+ | `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), unless the block has `onViewSaveAs` actions. The app stores views; update `views` (and `activeView`) with the result. |
439
+ | `onViewSaveAs` | `{ view }` | Trigger when the user clicks Save as, in place of the built-in title and Shared popover, when the block has actions on it. Open your own dialog (for example a modal asking for a name and description), store the view, then update `views` and `activeView` as after `onViewSave`. |
440
+ | `onViewMenu` | `{ key, id }` | Trigger when the user picks a `viewMenu` item on a saved view tab, after its confirmation when the item has `confirm`. |
441
+ | `onViewDelete` | `{ id }` | Trigger when the user deletes a saved view from its tab menu (the default menu, without `viewMenu`). |
434
442
  | `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. |
435
443
  | `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`. |
436
444
  | `onCellMenuItem` | `{ row, rowKey, value, item, itemIndex }` | Documentation reference - the event fired is the `eventName` of each item in a `menu` cell. |
@@ -1,6 +1,6 @@
1
1
  # TiptapInput
2
2
 
3
- Rich-text editor built on TipTap. Supports bold, italic, strike-through, highlights, headings, lists, tables, links, and drag/drop or paste image uploads via a configurable upload-policy request (`uploadPolicyRequestId`) — any storage provider (S3, GCS, Azure). Configure `downloadPolicyRequestId` to resolve inserted image URLs through a download request.
3
+ Rich-text editor built on TipTap. Supports bold, italic, strike-through, highlights, headings, lists, tables, links, and drag/drop or paste image uploads via a configurable upload-policy request (`uploadPolicyRequestId`) — any storage provider (S3, GCS, Azure). Configure `downloadPolicyRequestId` to resolve inserted image URLs through a download request, or `imageSrc` to save a stable app URL such as a [link endpoint](/api#link-endpoints), which lets the bucket stay private.
4
4
 
5
5
  ```yaml
6
6
  - id: tiptap_default
@@ -207,7 +207,8 @@ Rich-text editor built on TipTap. Supports bold, italic, strike-through, highlig
207
207
  | `link.defaultProtocol` | string | `"https"` | Protocol prefixed to URLs that omit one (e.g. "https"). |
208
208
  | `placeholder` | string | - | Placeholder shown when the editor is empty. |
209
209
  | `rows` | integer | - | Fix the editor height to exactly this many rows. Takes precedence over autoSize. |
210
- | `downloadPolicyRequestId` | string | - | Id of a download request (e.g. AwsS3PresignedGetObject) used to resolve the inserted image URL after upload. Inline images persist in saved content, so the request should set public: true (and the upload request the provider public-read acl) to return a stable, non-expiring URL. When unset, a legacy unsigned object URL is constructed from the upload response (S3-shaped, deprecated). |
210
+ | `imageSrc` | object | - | Optional _function that receives { key, bucket, name, type } of an uploaded image and returns the src saved for it, typically a stable app URL such as a link endpoint (/api/endpoints/&lt;endpointId>/&lt;key>) that redirects the signed-in caller to a fresh presigned URL, so the bucket can stay private. Takes precedence over downloadPolicyRequestId: when set, no download request runs. |
211
+ | `downloadPolicyRequestId` | string | - | Id of a download request (e.g. AwsS3PresignedGetObject) used to resolve the inserted image URL after upload. Inline images persist in saved content, so the request should set public: true (and the upload request the provider public-read acl) to return a stable, non-expiring URL. Ignored when imageSrc is set, which takes precedence. When neither is set, a legacy unsigned object URL is constructed from the upload response (S3-shaped, deprecated). |
211
212
  | `s3PostPolicyRequestId` | string | - | Deprecated — use uploadPolicyRequestId instead. |
212
213
  | `uploadPolicyRequestId` | string | - | Id of an upload-policy request (e.g. AwsS3PresignedPostPolicy, GcsSignedPostPolicy, AzureBlobUploadSas). When set, images dragged or pasted into the editor are uploaded via that request and inserted as &lt;img> nodes. Leave unset to disable image uploads. |
213
214
  | `size` | string | - | Label size forwarded to the Label block. Enum: `small`, `middle`, `large`. |
@@ -1,6 +1,6 @@
1
1
  # TiptapMentionInput
2
2
 
3
- Rich-text editor with @-mention support. Same feature set as TiptapInput, plus a mention dropdown populated from a static options list or a request. Mention options can be marked as groups (roles, teams, queues) to render under their own menu section, as distinctly coloured chips, and with a hover popover listing the group's current members. See the guide below.
3
+ Rich-text editor with @-mention support. Same feature set as TiptapInput, plus a mention dropdown populated from a static options list or a request. Mention options can be marked as groups (roles, teams, queues) to render under their own menu section, as distinctly coloured chips, and with a hover popover listing the group's current members. Set `imageSrc` to save pasted images at a stable app URL such as a [link endpoint](/api#link-endpoints). See the guide below.
4
4
 
5
5
  ## Group mentions
6
6
 
@@ -452,7 +452,8 @@ A mixed `options` array — people alongside group options carrying `tag.section
452
452
  | `mentionsRequestId` | string | - | Id of a request used to populate mention options. When set, the block registers a __getTipTapMentions event that calls that request. |
453
453
  | `placeholder` | string | - | Placeholder shown when the editor is empty. |
454
454
  | `rows` | integer | - | Fix the editor height to exactly this many rows. Takes precedence over autoSize. |
455
- | `downloadPolicyRequestId` | string | - | Id of a download request (e.g. AwsS3PresignedGetObject) used to resolve the inserted image URL after upload. Inline images persist in saved content, so the request should set public: true (and the upload request the provider public-read acl) to return a stable, non-expiring URL. When unset, a legacy unsigned object URL is constructed from the upload response (S3-shaped, deprecated). |
455
+ | `imageSrc` | object | - | Optional _function that receives { key, bucket, name, type } of an uploaded image and returns the src saved for it, typically a stable app URL such as a link endpoint (/api/endpoints/&lt;endpointId>/&lt;key>) that redirects the signed-in caller to a fresh presigned URL, so the bucket can stay private. Takes precedence over downloadPolicyRequestId: when set, no download request runs. |
456
+ | `downloadPolicyRequestId` | string | - | Id of a download request (e.g. AwsS3PresignedGetObject) used to resolve the inserted image URL after upload. Inline images persist in saved content, so the request should set public: true (and the upload request the provider public-read acl) to return a stable, non-expiring URL. Ignored when imageSrc is set, which takes precedence. When neither is set, a legacy unsigned object URL is constructed from the upload response (S3-shaped, deprecated). |
456
457
  | `s3PostPolicyRequestId` | string | - | Deprecated — use uploadPolicyRequestId instead. |
457
458
  | `uploadPolicyRequestId` | string | - | Id of an upload-policy request (e.g. AwsS3PresignedPostPolicy, GcsSignedPostPolicy, AzureBlobUploadSas). When set, images dragged or pasted into the editor are uploaded via that request. |
458
459
  | `size` | string | - | Label size forwarded to the Label block. Enum: `small`, `middle`, `large`. |
@@ -363,7 +363,7 @@ blocks:
363
363
  The `LOWDEFY_SERVER_BASE_PATH` environment variable configuration option has been removed. To configure a base path, use the `config.basePath` configuration option.
364
364
 
365
365
  ``yaml
366
- lowdefy: 7.0.0
366
+ lowdefy: 7.2.0
367
367
 
368
368
  config:
369
369
  basePath: /foo
@@ -371,7 +371,7 @@ config:
371
371
 
372
372
  The `_build.env` operator can be used to set the base path using an environment variable:
373
373
  ```yaml
374
- lowdefy: 7.0.0
374
+ lowdefy: 7.2.0
375
375
 
376
376
  config:
377
377
  basePath:
@@ -97,42 +97,44 @@ events:
97
97
  type: CallAPI
98
98
  params:
99
99
  endpointId: get_products
100
+ holdValue: true # Without holdValue, _api returns null while the call is loading
100
101
  - id: set_products_list
101
102
  type: SetState
102
103
  params:
103
- products_list
104
- _api: fetch_products.response.products
104
+ products_list:
105
+ _api: get_products.response.products
105
106
 
106
107
  blocks:
107
108
  - id: loading_text
108
109
  type: Html
109
110
  visible:
110
- _api: fetch_products.loading # Show loading text while API is loading
111
+ _api: get_products.loading # Show loading text while API is loading
111
112
  properties:
112
113
  html: '<div class="secondary">Loading...</div>'
113
114
 
114
115
  - id: error_message
115
116
  type: Alert
116
117
  visible:
117
- _not:
118
- _api: fetch_products.success
118
+ _eq: # success is null while the call is loading
119
+ - _api: get_products.success
120
+ - false
119
121
  properties:
120
122
  type: error
121
123
  message:
122
124
  _if:
123
125
  test:
124
- _api: fetch_products.error
126
+ _api: get_products.error
125
127
  then:
126
- _api: fetch_products.error.message
128
+ _api: get_products.error.message
127
129
  else: 'An error occurred'
128
130
 
129
131
  - id: products_list
130
132
  type: List
131
133
  visible:
132
134
  _and:
133
- - _api: fetch_products.success
135
+ - _api: get_products.success
134
136
  - _not:
135
- _api: fetch_products.loading
137
+ _api: get_products.loading
136
138
  ```
137
139
 
138
140
  ###### Working with multiple API calls: