@kronor/dtv 10.1.1 → 12.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.
package/README.md CHANGED
@@ -34,13 +34,19 @@ Key props you can pass to `App` (or via `dtv.renderTableView` in `main.tsx`):
34
34
 
35
35
  - `graphqlHost` / `requestHeaders`: GraphQL endpoint + HTTP headers. Pass `{}` when no custom headers are needed.
36
36
  - `aiIntegration`: AI provider used by the AI Filter Assistant. Either the built-in Gemini integration, `{ type: 'builtInGemini', geminiApiKey }`, or a custom provider (e.g. AWS Bedrock), `{ type: 'custom', requestAiFilter }`. The `requestAiFilter` function receives `{ prompt, filterGroups, userPrompt }` — where `prompt` is the fully-built prompt — and must return the model response: either the raw text containing a JSON object mapping filter IDs to `FilterFormState`, or that object already parsed.
37
- - `viewsJson`: JSON string array of view definitions (each view.json parsed at runtime).
37
+ - `viewsJson`: JSON string array of view definitions (each view.json parsed at runtime). `views` takes them already parsed instead. When the selected view's source, function arguments, `staticConditions` or `staticOrdering` change, the table asks for its first page again and clears the row selection; filters, ordering and rows per page stay.
38
38
  - `showViewsMenu`: Toggle the views dropdown menu (default: `false`).
39
39
  - `showViewTitle`: Toggle the view title heading (default: `false`).
40
40
  - `showCsvExportButton`: Toggle the "Export page to CSV" button (default: `false`). When enabled, current page rows are exported using PrimeReact's built-in DataTable CSV exporter.
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,6 +81,7 @@ 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
87
  - Data is fetched via GraphQL using `graphql-request` (see `src/framework/data.ts`).