@kronor/dtv 11.0.0 → 13.0.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 (32) hide show
  1. package/README.md +8 -1
  2. package/dist/cli/config/loadConfig.js +7 -6
  3. package/dist/index.es.js +30329 -37038
  4. package/dist/types/App.d.ts +11 -4
  5. package/dist/types/components/AIAssistantForm.d.ts +1 -1
  6. package/dist/types/components/ActionButtons.d.ts +5 -14
  7. package/dist/types/components/Autocomplete.d.ts +2 -2
  8. package/dist/types/components/FilterForm.d.ts +2 -2
  9. package/dist/types/components/FilterStatePills.d.ts +1 -1
  10. package/dist/types/components/LoadingOverlay.d.ts +1 -1
  11. package/dist/types/components/PhoneNumberFilter.d.ts +2 -1
  12. package/dist/types/components/SavedFilterList.d.ts +1 -1
  13. package/dist/types/components/SpeechInput.d.ts +1 -1
  14. package/dist/types/components/Table.d.ts +1 -1
  15. package/dist/types/components/TablePagination.d.ts +1 -1
  16. package/dist/types/components/UserPreferencesPanel.d.ts +1 -1
  17. package/dist/types/framework/actions.d.ts +5 -2
  18. package/dist/types/framework/analytics.d.ts +1 -1
  19. package/dist/types/framework/cell-renderer-components/CurrencyAmount.d.ts +1 -1
  20. package/dist/types/framework/cell-renderer-components/LayoutHelpers.d.ts +4 -4
  21. package/dist/types/framework/cell-renderer-components/Link.d.ts +1 -1
  22. package/dist/types/framework/cell-renderer-components/Mapping.d.ts +1 -1
  23. package/dist/types/framework/data.d.ts +1 -3
  24. package/dist/types/framework/fetch-error.d.ts +6 -2
  25. package/dist/types/framework/filters.d.ts +1 -1
  26. package/dist/types/framework/graphql-client.d.ts +28 -0
  27. package/dist/types/framework/state/app-state.d.ts +32 -1
  28. package/dist/types/lib/index.d.ts +5 -0
  29. package/dist/types/views/payment-requests/components/NoRowsExtendDateRange.d.ts +1 -1
  30. package/docs/analytics.md +7 -6
  31. package/docs/api/runtime.md +2 -0
  32. package/package.json +11 -12
package/README.md CHANGED
@@ -41,6 +41,12 @@ Key props you can pass to `App` (or via `dtv.renderTableView` in `main.tsx`):
41
41
  - `showPopoutButton`: Toggle the Popout button that opens the table view in a fullscreen overlay (default: `true`). Set to `false` to suppress this UI in embedded contexts.
42
42
  - `externalRuntime`: Provide a runtime override for cell renderers / query transforms.
43
43
  - `syncFilterStateToUrl`: Persist applied filter state into the `dtv-filter-state` URL param (default: `false`).
44
+ - `actions`: Buttons added to the toolbar after the built-in ones (`ActionDefinition[]`). An action's `onClick` gets an `ActionAPI`: the view, the draft filter state, the selected rows, the rows on screen (`shownRows`), `setFilterState`/`applyFilters`/`refetch`, `showToast`, query builders and user data. While its promise is pending, the button shows the action running and cannot be clicked again. Each action has an `id`, unique among the table's actions: analytics name the action by it, and `apiRef.current.runAction` finds it by it.
45
+ - `apiRef`: A React ref that DTV sets to its imperative API (`DTVAPI`) while the table is mounted:
46
+ - `fetchData()`: asks for the page the user is on again, e.g. after a mutation elsewhere.
47
+ - `rowSelection.reset()`: clears the row selection.
48
+ - `rowExpansion.collapseAll()` / `expandAll()` / `reset()`: collapses or expands the rows on the current page; `reset` collapses them.
49
+ - `runAction(id)`: runs the action with that `id` as a click on its button would, for a host that starts an action from a control of its own, e.g. with the toolbar hidden. The button shows it running, a run while it is running or disabled does nothing, and it reports the same analytics and failure toast. Does nothing, with a warning, for an id no action has.
44
50
 
45
51
  Example:
46
52
  ```ts
@@ -75,9 +81,10 @@ React and ReactDOM 19 are peer dependencies; ensure they are installed in the ho
75
81
  - **AI Integration:** The AI assistant (see `src/components/AIAssistantForm.tsx` and `src/components/aiAssistant.ts`) can generate filters, which must set `aiGenerated: true`.
76
82
  - **View Registration:** Each view (e.g., `paymentRequest.tsx`) exports a `View` object with a `filterSchema`, `columnDefinitions`, and a GraphQL query.
77
83
  - **Type Safety:** All filter and view schemas are strongly typed. When adding new filters, always specify all required fields.
84
+ - **App State Before Effects:** The table's state and its effects live in `src/framework/state/app-state.ts`: messages, pure transitions, and the commands `useAppState` runs (requests, user data writes, analytics, toolbar actions). Before adding a `useEffect`, `useLayoutEffect`, ref or `useState` to `App.tsx` for table behaviour, consider a message and a command instead. Transitions are tested as plain functions in `app-state.test.ts`, messages are handled in the order they are sent, and `useAppState` already hands commands the values of the latest render, which is what refs in `App.tsx` usually work around. `DTVAPI.runAction` is an example: a first version kept the running actions in refs and set the API in a layout effect, and as `actionRequested`/`actionEnded` and a `runAction` command it needs neither. Effects in `App.tsx` are for what the state cannot own, such as the DOM.
78
85
 
79
86
  ## Integration & Data Flow
80
- - Data is fetched via GraphQL using `graphql-request` (see `src/framework/data.ts`).
87
+ - Data is fetched via GraphQL with DTV's own `fetch`-based client (see `src/framework/graphql-client.ts` and `src/framework/data.ts`).
81
88
  - Views define their own GraphQL queries and filter schemas.
82
89
  - Filter expressions are serialized/deserialized using helpers in `src/framework/filters.ts`.
83
90
  - Unified URL Filter Param: Both share links and persistence use a single base64 URL-safe encoded parameter `dtv-filter-state`. Enable syncing by passing `syncFilterStateToUrl: true` to `dtv.renderTableView` (or `?sync-filter-state-to-url=true` in dev). The param is updated only when filters are applied (not on every change). It names the view the filter state belongs to, so a shared link opens that view. When disabled, a one-off link is consumed (param removed after load).
@@ -48,17 +48,18 @@ async function importConfig(abs) {
48
48
  const tmpFile = path.join(path.dirname(abs), `.${path.basename(abs)}.dtv-tmp.${Date.now()}.mjs`);
49
49
  await fs.writeFile(tmpFile, transpiled.outputText, 'utf8');
50
50
  try {
51
- const tmpUrl = pathToFileURL(tmpFile).href;
52
- const mod = await import(`${tmpUrl}?t=${Date.now()}`);
51
+ // The file name is new on every run, so the import is never served from cache
52
+ const mod = await import(pathToFileURL(tmpFile).href);
53
53
  return (mod.default ?? mod.config ?? mod);
54
54
  }
55
55
  finally {
56
56
  await fs.unlink(tmpFile).catch(() => undefined);
57
57
  }
58
58
  }
59
- // JS/MJS/CJS (or any Node-supported module) can be imported directly.
60
- // Cache-bust import to allow repeated runs.
61
- const mod = await import(`${url}?t=${Date.now()}`);
59
+ // JS/MJS/CJS (or any Node-supported module) can be imported directly. The CLI loads
60
+ // its config once per process, so the import needs no cache-busting query (which
61
+ // Jest 30.5's module loader would also take for part of the file name).
62
+ const mod = await import(url);
62
63
  return (mod.default ?? mod.config ?? mod);
63
64
  })();
64
65
  if (!isRecord(cfg)) {
@@ -110,7 +111,7 @@ export async function loadDefinitionsConfig(configPath) {
110
111
  catch (err) {
111
112
  throw new Error(`Failed to load ${configPath}: ${err instanceof Error ? err.message : String(err)}\n` +
112
113
  'If it fails for want of what only typegen needs (e.g. a secret for the schema), make `schema` a function: ' +
113
- 'it is called by `dtv typegen` only.');
114
+ 'it is called by `dtv typegen` only.', { cause: err });
114
115
  }
115
116
  validateScan(cfg);
116
117
  const scan = cfg.scan;