@uipath/ui-widgets-validation-station 1.1.0 → 1.3.0-rc.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 (94) hide show
  1. package/README.md +361 -202
  2. package/dist/ValidationStation.d.ts +5 -2
  3. package/dist/ValidationStation.d.ts.map +1 -1
  4. package/dist/ValidationStation.js +10 -4
  5. package/dist/ValidationStation.js.map +1 -1
  6. package/dist/ValidationStation.stories.d.ts.map +1 -1
  7. package/dist/ValidationStation.stories.js +3 -2
  8. package/dist/ValidationStation.stories.js.map +1 -1
  9. package/dist/bucketArtifactsUtil.d.ts.map +1 -1
  10. package/dist/bucketArtifactsUtil.js +28 -12
  11. package/dist/bucketArtifactsUtil.js.map +1 -1
  12. package/dist/index.d.ts +5 -2
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +3 -0
  15. package/dist/index.js.map +1 -1
  16. package/dist/ixpUtil.d.ts +6 -0
  17. package/dist/ixpUtil.d.ts.map +1 -0
  18. package/dist/ixpUtil.js +9 -0
  19. package/dist/ixpUtil.js.map +1 -0
  20. package/dist/loadValidationStationWc.d.ts +3 -1
  21. package/dist/loadValidationStationWc.d.ts.map +1 -1
  22. package/dist/loadValidationStationWc.js +1 -15
  23. package/dist/loadValidationStationWc.js.map +1 -1
  24. package/dist/payloadSource.d.ts +19 -0
  25. package/dist/payloadSource.d.ts.map +1 -0
  26. package/dist/payloadSource.js +12 -0
  27. package/dist/payloadSource.js.map +1 -0
  28. package/dist/processedDocument/artifacts.d.ts +15 -0
  29. package/dist/processedDocument/artifacts.d.ts.map +1 -0
  30. package/dist/processedDocument/artifacts.js +86 -0
  31. package/dist/processedDocument/artifacts.js.map +1 -0
  32. package/dist/processedDocument/dom.d.ts +7 -0
  33. package/dist/processedDocument/dom.d.ts.map +1 -0
  34. package/dist/processedDocument/dom.js +43 -0
  35. package/dist/processedDocument/dom.js.map +1 -0
  36. package/dist/processedDocument/errors.d.ts +20 -0
  37. package/dist/processedDocument/errors.d.ts.map +1 -0
  38. package/dist/processedDocument/errors.js +27 -0
  39. package/dist/processedDocument/errors.js.map +1 -0
  40. package/dist/processedDocument/payload.d.ts +14 -0
  41. package/dist/processedDocument/payload.d.ts.map +1 -0
  42. package/dist/processedDocument/payload.js +34 -0
  43. package/dist/processedDocument/payload.js.map +1 -0
  44. package/dist/processedDocument/platformClient.d.ts +22 -0
  45. package/dist/processedDocument/platformClient.d.ts.map +1 -0
  46. package/dist/processedDocument/platformClient.js +131 -0
  47. package/dist/processedDocument/platformClient.js.map +1 -0
  48. package/dist/processedDocument/review.d.ts +20 -0
  49. package/dist/processedDocument/review.d.ts.map +1 -0
  50. package/dist/processedDocument/review.js +28 -0
  51. package/dist/processedDocument/review.js.map +1 -0
  52. package/dist/processedDocument/save.d.ts +22 -0
  53. package/dist/processedDocument/save.d.ts.map +1 -0
  54. package/dist/processedDocument/save.js +73 -0
  55. package/dist/processedDocument/save.js.map +1 -0
  56. package/dist/processedDocument/spans.d.ts +4 -0
  57. package/dist/processedDocument/spans.d.ts.map +1 -0
  58. package/dist/processedDocument/spans.js +65 -0
  59. package/dist/processedDocument/spans.js.map +1 -0
  60. package/dist/processedDocument/types.d.ts +45 -0
  61. package/dist/processedDocument/types.d.ts.map +1 -0
  62. package/dist/processedDocument/types.js +2 -0
  63. package/dist/processedDocument/types.js.map +1 -0
  64. package/dist/saveHandlers.d.ts +3 -1
  65. package/dist/saveHandlers.d.ts.map +1 -1
  66. package/dist/saveHandlers.js +40 -11
  67. package/dist/saveHandlers.js.map +1 -1
  68. package/dist/saveValidatedDataUtil.d.ts.map +1 -1
  69. package/dist/saveValidatedDataUtil.js +9 -0
  70. package/dist/saveValidatedDataUtil.js.map +1 -1
  71. package/dist/subcomponents/CompactBusinessRules.d.ts.map +1 -1
  72. package/dist/subcomponents/CompactBusinessRules.js +2 -1
  73. package/dist/subcomponents/CompactBusinessRules.js.map +1 -1
  74. package/dist/subcomponents/CompactFieldsForm.d.ts.map +1 -1
  75. package/dist/subcomponents/CompactFieldsForm.js +4 -2
  76. package/dist/subcomponents/CompactFieldsForm.js.map +1 -1
  77. package/dist/subcomponents/CompactTableEditor.d.ts.map +1 -1
  78. package/dist/subcomponents/CompactTableEditor.js +4 -2
  79. package/dist/subcomponents/CompactTableEditor.js.map +1 -1
  80. package/dist/subcomponents/shared.d.ts +4 -4
  81. package/dist/subcomponents/shared.d.ts.map +1 -1
  82. package/dist/subcomponents/shared.js.map +1 -1
  83. package/dist/subcomponents/useWcElement.d.ts +2 -2
  84. package/dist/subcomponents/useWcElement.d.ts.map +1 -1
  85. package/dist/subcomponents/useWcElement.js +1 -1
  86. package/dist/subcomponents/useWcElement.js.map +1 -1
  87. package/dist/types.d.ts +62 -17
  88. package/dist/types.d.ts.map +1 -1
  89. package/dist/types.js.map +1 -1
  90. package/dist/useResolvedArtifacts.d.ts +26 -7
  91. package/dist/useResolvedArtifacts.d.ts.map +1 -1
  92. package/dist/useResolvedArtifacts.js +42 -29
  93. package/dist/useResolvedArtifacts.js.map +1 -1
  94. package/package.json +4 -4
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @uipath/ui-widgets-validation-station
2
2
 
3
- A React wrapper for the UiPath Document Understanding Validation Station. It handles web component loading, bucket artifact fetching, and exposes a declarative props API for all Validation Station features.
3
+ A React wrapper for the UiPath Document Understanding **Validation Station**. It handles web component loading and bucket artifact fetching, and exposes a declarative props API for every Validation Station feature.
4
4
 
5
5
  ## Installation
6
6
 
@@ -10,67 +10,78 @@ npm install @uipath/ui-widgets-validation-station
10
10
 
11
11
  ### Peer dependencies
12
12
 
13
- ```
14
- react >= 19.2.0
15
- react-dom >= 19.2.0
16
- @uipath/uipath-typescript >= 1.4.2
13
+ ```bash
14
+ npm install react@^19.2.0 react-dom@^19.2.0 @uipath/uipath-typescript@^1.5.1
17
15
  ```
18
16
 
19
17
  ## Quick start
20
18
 
21
- > **Note:** Add either `light` or `dark` class to your HTML `<body>` element to enable proper theming.
19
+ > **Note: Theming**
20
+ > Add either a `light` or `dark` class to your HTML `<body>` element to enable proper theming.
22
21
 
23
22
  ```tsx
24
23
  import {
25
24
  configureValidationStationWc,
26
25
  ValidationStation,
27
- ValidationStationLanguage,
28
26
  } from "@uipath/ui-widgets-validation-station";
29
27
  import { UiPath } from "@uipath/uipath-typescript/core";
30
28
  import type { DuFramework } from "@uipath/uipath-typescript/document-understanding";
29
+ import { useEffect, useState } from "react";
31
30
 
32
31
  // Once, at app startup — loads the web component from `du-vs-wc`, next to
33
32
  // your app's own root by default. See "Hosting the web component" below.
34
33
  configureValidationStationWc();
35
34
 
36
- const sdk = new UiPath({
37
- baseUrl: "https://cloud.uipath.com",
38
- orgName: "your-org",
39
- tenantName: "your-tenant",
40
- secret: "your-secret",
41
- });
42
-
43
- await sdk.initialize();
35
+ function App({ task }: { task: { data: DuFramework.ContentValidationData } }) {
36
+ const [sdk, setSdk] = useState<UiPath | null>(null);
44
37
 
45
- function App() {
46
- return (
47
- <ValidationStation
48
- sdk={sdk}
49
- data={selectedTask.data as DuFramework.ContentValidationData}
50
- />
51
- );
38
+ useEffect(() => {
39
+ const init = async () => {
40
+ const uipath = new UiPath({
41
+ baseUrl: "https://api.uipath.com",
42
+ orgName: "your-org",
43
+ tenantName: "your-tenant",
44
+ clientId: "your-client-id",
45
+ // `OR.Buckets` is the widget's own need; `OR.Tasks` is for the host
46
+ // code that fetches the task and completes it after submit.
47
+ scope: "OR.Buckets OR.Tasks",
48
+ redirectUri: "http://localhost:3000/callback",
49
+ });
50
+ await uipath.initialize();
51
+ setSdk(uipath);
52
+ };
53
+ init();
54
+ }, []);
55
+
56
+ if (!sdk) return <div>Loading...</div>;
57
+
58
+ return <ValidationStation sdk={sdk} data={task.data} />;
52
59
  }
53
60
  ```
54
61
 
55
- > `theme` defaults to `"light"` and `language` defaults to `ValidationStationLanguage.English`, so the minimal mount just needs `sdk` and `data`.
62
+ > **Note: `initialize()` drives the OAuth redirect**
63
+ > Under OAuth, `initialize()` navigates the browser to the identity provider and completes the flow when it returns, so keep it inside an effect rather than at module scope, and serve `redirectUri` as a route of this same app — it must match a URI registered on the external application exactly, scheme and path included.
56
64
 
57
- > You must call `configureValidationStationWc` once before rendering any widget
58
- > from this package, and host the web component's files where it expects them
59
- > (a `deploymentUrl` default handles this for most hosts — override it if
60
- > yours doesn't). See [Hosting the web component](#hosting-the-web-component).
65
+ `theme` defaults to `"light"` and `language` defaults to `ValidationStationLanguage.English`, so the minimal mount just needs `sdk` and `data`.
66
+
67
+ > **Warning: Call `configureValidationStationWc` first**
68
+ > You must call it once before rendering any widget from this package, and host the web component's files where it expects them. A `deploymentUrl` default handles this for most hosts — override it if yours doesn't. See [Hosting the web component](#hosting-the-web-component).
61
69
 
62
70
  ## Data sources
63
71
 
64
- The widget needs a taxonomy, an extraction result and a document DOM. There are two mutually-exclusive ways to give it those:
72
+ The widget needs a taxonomy, an extraction result and a document DOM. There are three mutually exclusive ways to give it those:
73
+
74
+ | Mode | Pass | Who fetches | Who writes back |
75
+ | ---------------------- | ---------------------------- | ------------------------------------------------------------- | ----------------------------------------------------- |
76
+ | **Self-fetching** | `sdk` + `data` | The widget, from the bucket paths on `ContentValidationData` | The widget, to `ValidatedExtractionResultsPath` |
77
+ | **Self-fetching, IXP** | `sdk` + `processedDocument` | The widget, through the Flow run that produced the document | The widget, as a review recorded against the Flow run |
78
+ | **Pre-fetched** | `artifacts` (+ `documentId`) | You — hand it a `DuDocumentArtifacts` object you already hold | You, from the request the widget emits |
65
79
 
66
- | Mode | Pass | Who fetches | Who writes back |
67
- | ----------------- | ---------------------------- | ------------------------------------------------------------- | ----------------------------------------------- |
68
- | **Self-fetching** | `sdk` + `data` | The widget, from the bucket paths on `ContentValidationData` | The widget, to `ValidatedExtractionResultsPath` |
69
- | **Pre-fetched** | `artifacts` (+ `documentId`) | You — hand it a `DuDocumentArtifacts` object you already hold | You, from the request the widget emits |
80
+ If both `data` and `processedDocument` are set, `data` wins.
70
81
 
71
82
  **The outputs do not change with the mode.** `onSubmit`, `onSaveAsDraft` and `onReportException` fire for every user action either way, and always carry the request the web component produced. The only difference is a second argument: when the widget persisted the data itself, it passes the outcome too.
72
83
 
73
- Pre-fetched mode is what you want when the document does not live in a storage bucket, when the artifacts are already in memory (e.g. fetched once and shared with the [subcomponents](./docs/validation-station-subcomponents.md)), or when persistence goes somewhere other than `ValidatedExtractionResultsPath`.
84
+ Pre-fetched mode is what you want when the document does not live in a storage bucket, when the artifacts are already in memory (e.g. fetched once and shared with the [subcomponents](https://github.com/UiPath/uipath-ui-widgets/blob/develop/packages/validation-station/docs/validation-station-subcomponents.md)), or when persistence goes somewhere other than `ValidatedExtractionResultsPath`.
74
85
 
75
86
  ```tsx
76
87
  import {
@@ -93,18 +104,44 @@ Every bucket call is scoped to the folder `data` names — `FolderId`, or `Folde
93
104
 
94
105
  The two modes can be mixed: pass `artifacts` **and** `sdk` + `data` to skip the fetch while keeping the built-in write-back — `onSubmit` then receives the outcome as well.
95
106
 
96
- > `DuDocumentArtifacts` is `{ taxonomy, extractionResult, dom, text, customizationInfo, original }` — `original` is the base64-encoded document the viewer renders.
107
+ > **Info: `DuDocumentArtifacts`**
108
+ > `{ taxonomy, extractionResult, predictedExtractionResult?, dom, text, customizationInfo, original }` — `original` is the base64-encoded document the viewer renders. In `DuDocumentArtifacts`, `taxonomy` and `extractionResult` are UiPath DU contracts. `ValidationStation` also takes `IxpDocumentArtifacts`, the same shape with both in the IXP representation (an `IXPTaxonomy` JSON Schema and an `IXPExtraction`) and no `predictedExtractionResult`; the subcomponents take `DuDocumentArtifacts` only.
109
+
110
+ ### Comparing against the prediction
111
+
112
+ `predictedExtractionResult` is the model's prediction — the extraction output nobody edited — as opposed to `extractionResult`, the result the user reviews. Self-fetching fills it from `AutomaticExtractionResultsPath`; in pre-fetched mode it is optional, and a hand-built `DuDocumentArtifacts` without it is still valid. It is a UiPath DU contract, so only a Document Understanding document carries one — an IXP document (including a Flow `ProcessedDocument`) has no prediction.
113
+
114
+ By itself it changes nothing visible. It drives the `EnablePredictionDiff` customization flag (compact mode, on `ValidationStation`, `CompactFieldsForm` and `CompactTableEditor`): where the prediction differs from the current values, the element shows the predicted value with a button that takes it over. Like every customization flag, it lives under `FeatureCustomization` in `customizationInfo` — typed by the exported `ICustomizationInfoDTO` / `IFeatureCustomization`:
115
+
116
+ ```ts
117
+ import type { ICustomizationInfoDTO } from "@uipath/ui-widgets-validation-station";
118
+
119
+ // Merge over what the bucket supplied rather than replacing it.
120
+ const fetched = artifacts.customizationInfo as
121
+ | ICustomizationInfoDTO
122
+ | undefined;
123
+ const withDiff = {
124
+ ...artifacts,
125
+ customizationInfo: {
126
+ ...fetched,
127
+ FeatureCustomization: {
128
+ ...fetched?.FeatureCustomization,
129
+ EnablePredictionDiff: true,
130
+ },
131
+ } satisfies ICustomizationInfoDTO,
132
+ };
133
+ ```
97
134
 
98
135
  ### Owning the round-trip
99
136
 
100
137
  Pre-fetched mode does not mean writing the bucket plumbing yourself. Everything the widget does internally is exported, so a host can drive the same flow:
101
138
 
102
- | Export | Use |
103
- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
104
- | `fetchDuDocumentArtifacts(sdk, data)` | Fetch `DuDocumentArtifacts` imperatively — outside render, ahead of time, or in a loader. |
105
- | `useDuDocumentArtifacts(sdk, data)` | The same fetch as a hook, for when the fetch belongs to a component's lifecycle. |
106
- | `submitValidatedData(sdk, data, request)` | The submit flow: `ProcessExtractedData`, then upload to `ValidatedExtractionResultsPath`. |
107
- | `saveValidatedDataAsDraft(sdk, data, request)` | The draft flow: upload `validatedData` straight to the bucket. |
139
+ | Export | Use |
140
+ | ---------------------------------------------- | ---------------------------------------------------------------------------------------- |
141
+ | `fetchDuDocumentArtifacts(sdk, data)` | Fetch `DuDocumentArtifacts` imperatively — outside render, ahead of time, or in a loader |
142
+ | `useDuDocumentArtifacts(sdk, data)` | The same fetch as a hook, for when the fetch belongs to a component's lifecycle |
143
+ | `submitValidatedData(sdk, data, request)` | The submit flow: `ProcessExtractedData`, then upload to `ValidatedExtractionResultsPath` |
144
+ | `saveValidatedDataAsDraft(sdk, data, request)` | The draft flow: upload `validatedData` straight to the bucket |
108
145
 
109
146
  ```tsx
110
147
  import {
@@ -139,45 +176,91 @@ function HostOwnedReview({ sdk, data }) {
139
176
  }
140
177
  ```
141
178
 
142
- > Handle **both** callbacks. The widget always offers "Save as draft", so leaving `onSaveAsDraft` unwired means a draft click persists nothing.
179
+ > **Warning: Handle both callbacks**
180
+ > The widget always offers **Save as draft**, so leaving `onSaveAsDraft` unwired means a draft click persists nothing.
143
181
 
144
182
  The request payloads are exported too — `IVsSaveValidatedDataRequest`, `IVsSaveValidatedDataAsDraftRequest` and `IVsSaveExceptionReportRequest` — so handlers declared outside JSX can name their parameter.
145
183
 
146
- A full working example lives in the repo's sample app under `samples/pages/ValidationStation/ValidationStationPrefetchedPage.tsx`.
184
+ ### IXP (`ProcessedDocument`)
185
+
186
+ A Flow IDP node emits a `ProcessedDocument` rather than a `ContentValidationData`. It carries the taxonomy (an `IXPTaxonomy`) and the result (an `IXPExtraction`) inline, plus `metadata` naming the run that produced it — `traceId`, `spanId` and `folderKey`. The document, its DOM and its OCR text are read through that run's trace.
187
+
188
+ ```tsx
189
+ <ValidationStation
190
+ sdk={sdk}
191
+ processedDocument={task.data}
192
+ onSubmit={(request) => completeTask(request.validatedData)}
193
+ />
194
+ ```
195
+
196
+ - **Loading.** The document opens on the result last saved against the producing span (a draft), else on the payload's `result`. `documentId` defaults to `metadata.traceId`.
197
+ - **Saving.** Submit and draft record the review against the producing span; report-as-exception records a rejection with the reason. `onSubmit`, `onSaveAsDraft` and `onReportException` receive the outcome as their second argument. `request.validatedData` is an `IXPExtraction`.
198
+ - **Record format.** A review is stored as `{ draft, extraction }` — `draft: true` for a draft, `false` for a submit — the shape the Angular Validation Station uses, so either reopens a review the other saved. A record in any other shape is ignored on load.
199
+ - **Completing the task is yours.** The downstream Flow node reads the validated result from the task completion, so complete it with `request.validatedData` whatever the outcome says.
200
+ - **Scope.** Only `ValidationStation` takes `processedDocument` or an IXP document; the [subcomponents](https://github.com/UiPath/uipath-ui-widgets/blob/develop/packages/validation-station/docs/validation-station-subcomponents.md) take Document Understanding documents (`DuDocumentArtifacts`) only.
201
+ - **OAuth scopes.** The `sdk`'s token needs `Traces.Api` (the run's spans, and the review record) and `OR.Buckets.Read` (the document, DOM and OCR text, via ECS). A coded action app completing the task also needs `OR.Tasks`. A missing scope surfaces as a 401/403 in the load or save error.
202
+ - **Hosting.** The artifacts are downloaded in the browser from pre-signed ECS storage URLs, so the host's origin must be in the ECS storage account's CORS rules. Coded apps (`https://{org}.{env}.uipath.host`) are.
203
+
204
+ The widget does this through exported functions, so a host that fetches up front runs exactly the same code:
205
+
206
+ | Export | Use |
207
+ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
208
+ | `fetchProcessedDocumentArtifacts(sdk, processedDocument)` | Fetch the `IxpDocumentArtifacts` — what the widget fetches given `processedDocument` |
209
+ | `submitProcessedDocument(sdk, processedDocument, request)` | Record a submitted review |
210
+ | `saveProcessedDocumentAsDraft(sdk, processedDocument, request)` | Record a draft — the one the next load opens on |
211
+ | `reportProcessedDocumentException(sdk, processedDocument, request)` | Record a rejection with the reviewer's reason. Replaces a saved draft |
212
+
213
+ ```tsx
214
+ const artifacts = await fetchProcessedDocumentArtifacts(sdk, processedDocument);
215
+
216
+ <ValidationStation
217
+ artifacts={artifacts}
218
+ onSubmit={async (request) => {
219
+ await submitProcessedDocument(sdk, processedDocument, request);
220
+ completeTask(request.validatedData);
221
+ }}
222
+ onSaveAsDraft={(request) =>
223
+ saveProcessedDocumentAsDraft(sdk, processedDocument, request)
224
+ }
225
+ />;
226
+ ```
227
+
228
+ The save functions are stateless: each one edits the span's newest review record, or creates it when there is none, so the widget and a host saving outside it always land on the same record.
147
229
 
148
230
  ## Props
149
231
 
150
- | Prop | Type | Required | Default | Description |
151
- | -------------------------------- | ---------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
152
- | `sdk` | `UiPath` | No\* | — | UiPath SDK instance for authentication and API calls. Required for self-fetching / persistence |
153
- | `data` | `ContentValidationData` | No\* | — | Document data containing the bucket paths, document ID, and the folder they live in — `FolderId` or `FolderKey`, whichever the producing activity set. Required for self-fetching / persistence |
154
- | `artifacts` | `DuDocumentArtifacts` | No\* | — | Pre-fetched document artifacts. When supplied, no bucket fetch is performed. \*Either `artifacts` or `sdk` + `data` must be provided |
155
- | `documentId` | `string` | No | — | Document id forwarded to the web component. Falls back to `data.DocumentId` — pass it in pre-fetched mode, where there is no `data` |
156
- | `theme` | `'light' \| 'dark' \| 'light-hc' \| 'dark-hc'` | No | `'light'` | Visual theme |
157
- | `language` | `ValidationStationLanguage` | No | `English` | UI language (see enum below) |
158
- | `isReadonly` | `boolean` | No | `false` | When `true`, renders in read-only mode |
159
- | `persistent` | `boolean` | No | `false` | Render the persistent element variant, which survives portal/DOM detachment (e.g. tab switches) |
160
- | `options` | `IValidationStationOptions` | No | — | Fine-grained UI feature flags, passed through to the element as given |
161
- | `save={{ validate: false }}` | `{ validate: boolean }` | No | — | Trigger **save as draft** |
162
- | `save={{ validate: true }}` | `{ validate: boolean }` | No | — | Trigger **submit** — runs validation first, then saves. |
163
- | `discardChanges` | `{ value: boolean }` | No | — | Trigger a discard-changes operation. Call `setDiscardChanges({ value: true })` (or `false` — the boolean is ignored) every time you want it to fire. Each call creates a brand-new object even if the content looks identical, and that's what the widget watches for — so calling it repeatedly with the same `{ value: true }` works just fine. |
164
- | `setFieldValueByPath` | `SetFieldValueByPath` | No | — | Set a field value addressed by a path of `{ fieldName, valueIndex }` segments |
165
- | `selectAndFocusFieldValueByPath` | `SelectAndFocusFieldValueByPath` | No | — | Select and focus a field value addressed by a path; focuses the document reference if any |
166
- | `deleteFieldValueByPath` | `DeleteFieldValueByPath` | No | — | Delete a field value addressed by a path |
167
-
168
- > The three save callbacks (`onSubmit`, `onSaveAsDraft`, `onReportException`) are documented in [the next section](#reacting-to-save--draft--exception-flows); the state callbacks in [Reading the document state](#reading-the-document-state).
169
-
170
- ### Reacting to save / draft / exception flows
232
+ | Prop | Type | Required | Default | Description |
233
+ | -------------------------------- | ---------------------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
234
+ | `sdk` | `UiPath` | No\* | — | UiPath SDK instance for authentication and API calls. Required for self-fetching / persistence |
235
+ | `data` | `ContentValidationData` | No\* | — | Document data containing the bucket paths, document ID, and the folder they live in — `FolderId` or `FolderKey`, whichever the producing activity set. Required for self-fetching / persistence |
236
+ | `processedDocument` | `ProcessedDocument` | No\* | — | A Flow IDP node's output. With `sdk`, the widget fetches its artifacts and records reviews through the producing run — see [IXP documents](#ixp-documents-processeddocument). Ignored when `data` is set |
237
+ | `artifacts` | `DuDocumentArtifacts \| IxpDocumentArtifacts` | No\* | — | Pre-fetched document artifacts. When supplied, no fetch is performed. \*Either `artifacts`, `sdk` + `data` or `sdk` + `processedDocument` must be provided |
238
+ | `documentId` | `string` | No | — | Document ID forwarded to the web component. Falls back to `data.DocumentId`, else `processedDocument.metadata.traceId` — pass it in pre-fetched mode |
239
+ | `theme` | `'light' \| 'dark' \| 'light-hc' \| 'dark-hc'` | No | `'light'` | Visual theme |
240
+ | `language` | `ValidationStationLanguage` | No | `English` | UI language (see [the enum](#language-enum)) |
241
+ | `isReadonly` | `boolean` | No | `false` | When `true`, renders in read-only mode |
242
+ | `persistent` | `boolean` | No | `false` | Render the persistent element variant, which survives portal/DOM detachment (e.g. tab switches) |
243
+ | `options` | `IValidationStationOptions` | No | — | Fine-grained UI feature flags, passed through to the element as given |
244
+ | `save={{ validate: false }}` | `{ validate: boolean }` | No | — | Trigger **save as draft** |
245
+ | `save={{ validate: true }}` | `{ validate: boolean }` | No | — | Trigger **submit** — runs validation first, then saves |
246
+ | `discardChanges` | `{ value: boolean }` | No | — | Trigger a discard-changes operation. Call `setDiscardChanges({ value: true })` (or `false` — the boolean is ignored) every time you want it to fire. Each call creates a brand-new object even if the content looks identical, and that is what the widget watches for |
247
+ | `setFieldValueByPath` | `SetFieldValueByPath` | No | — | Set a field value addressed by a path of `{ fieldName, valueIndex }` segments |
248
+ | `selectAndFocusFieldValueByPath` | `SelectAndFocusFieldValueByPath` | No | — | Select and focus a field value addressed by a path; focuses the document reference if any |
249
+ | `deleteFieldValueByPath` | `DeleteFieldValueByPath` | No | — | Delete a field value addressed by a path |
250
+
251
+ The three save callbacks (`onSubmit`, `onSaveAsDraft`, `onReportException`) are documented [below](#reacting-to-save-draft-and-exception-flows); the state callbacks in [Reading the document state](#reading-the-document-state).
252
+
253
+ ## Reacting to save, draft and exception flows
171
254
 
172
255
  The widget surfaces three user-initiated flows and reports each through exactly one callback, whichever mode it is in. Every callback receives the raw request; `result` is filled in only for the flows the widget persisted itself.
173
256
 
174
- | Callback | User action | Signature | What the widget does | What the host does |
175
- | ------------------- | ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
176
- | `onSubmit` | **Submit** | `(request, result?) => void` | With `sdk` + `data`: `processExtractedData`, then uploads to `ValidatedExtractionResultsPath`, and passes the outcome as `result`. Without: emits the request only. | React to `result`, or — when it is absent — persist the request yourself (`submitValidatedData` does exactly what the widget would have). |
177
- | `onSaveAsDraft` | **Save as draft** | `(request, result?) => void` | With `sdk` + `data`: uploads `validatedData` straight to the bucket (no `processExtractedData`). Without: emits the request only. | Same as above; the host-side equivalent is `saveValidatedDataAsDraft`. |
178
- | `onReportException` | **Report as exception** | `(request) => void` | Nothing — the widget never persists exceptions, in either mode. The reason is at `request.exceptionReport.Reason`. | Required if you want the report persisted — call `OrchestratorDuModule.submitExceptionReport(...)` yourself. |
257
+ | Callback | User action | Signature | What the widget does | What the host does |
258
+ | ------------------- | ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
259
+ | `onSubmit` | **Submit** | `(request, result?) => void` | With `sdk` + `data`: `processExtractedData`, then uploads to `ValidatedExtractionResultsPath`, and passes the outcome as `result`. Without: emits the request only | React to `result`, or — when it is absent — persist the request yourself (`submitValidatedData` does exactly what the widget would have) |
260
+ | `onSaveAsDraft` | **Save as draft** | `(request, result?) => void` | With `sdk` + `data`: uploads `validatedData` straight to the bucket (no `processExtractedData`). Without: emits the request only | Same as above; the host-side equivalent is `saveValidatedDataAsDraft` |
261
+ | `onReportException` | **Report as exception** | `(request, result?) => void` | With `sdk` + `processedDocument`: records the rejection against the Flow run and passes the outcome as `result`. Otherwise nothing — the reason is at `request.exceptionReport.Reason` | For any other source, persist it yourself — call `OrchestratorDuModule.submitExceptionReport(...)` |
179
262
 
180
- Submit/draft hand you a `SaveValidatedDataResult` (`{ success, error? }`) — the host owns all UI feedback (toast, retry, etc.); the widget does not surface failures itself. The exception callback hands you `documentId` and `reason` strings ready to forward to the SDK.
263
+ Submit and draft hand you a `SaveValidatedDataResult` (`{ success, error? }`) — the host owns all UI feedback (toast, retry, etc.); the widget does not surface failures itself. The exception callback hands you `documentId` and `reason` strings ready to forward to the SDK.
181
264
 
182
265
  All three fire on every user action, regardless of mode — that is the contract. Only `result` varies.
183
266
 
@@ -227,39 +310,58 @@ function App({ sdk, data, task }) {
227
310
  }
228
311
  ```
229
312
 
230
- > All three callbacks are optional, but failures are silent if you skip them — the widget surfaces no errors on its own. `onReportException` is the only place the report goes; without it the user's "Report as exception" click is a no-op.
313
+ > **Warning: Failures are silent if you skip the callbacks**
314
+ > All three callbacks are optional, but the widget surfaces no errors on its own. Outside a `processedDocument`, `onReportException` is the only place the report goes — without it, the user's **Report as exception** click is a no-op.
231
315
 
232
316
  ## Reading the document state
233
317
 
234
- These callbacks report the rest of the element's
235
- `IValidationStationStandaloneWcEventMap`; the three save flows are above.
318
+ These callbacks report the rest of the element's `IValidationStationStandaloneWcEventMap`; the three save flows are above.
236
319
 
237
320
  | Prop | Fires when |
238
321
  | ---------------------------------------- | ------------------------------------------------------------------------------------- |
239
- | `onExtractionResultChanged` | any change to the extraction result — needs `options={{ emitDtoStateChanges: true }}` |
240
- | `onLoaded` | the element finished loading |
241
- | `onDirtyChange` | unsaved changes appear or are cleared |
242
- | `onIsValidChange` | validity flips (`true` = no Must rule broken, no invalid values) |
243
- | `onDocumentTypeChanged` | the user picks another document type |
244
- | `onFieldValueSelected` | the user selects a field value |
245
- | `onFieldValueChanged` | the user edits a field value |
246
- | `onBusinessRulesEvaluated` | validation errors and business rules are re-evaluated |
247
- | `onSaveResult` | a `save` command completes |
248
- | `onSetFieldValueByPathResult` | a `setFieldValueByPath` command completes |
249
- | `onSelectAndFocusFieldValueByPathResult` | a `selectAndFocusFieldValueByPath` command completes |
250
- | `onDeleteFieldValueByPathResult` | a `deleteFieldValueByPath` command completes |
251
- | `onFieldsPanelWidthChanged` | the fields panel is resized (width in px) |
252
- | `onFieldsPanelSideChanged` | the panel moves to the other side of the viewer |
253
-
254
- **Commands need a loaded document.** `setFieldValueByPath`,
255
- `selectAndFocusFieldValueByPath` and `deleteFieldValueByPath` resolve their
256
- `path` against the taxonomy and the current extraction result, so one issued
257
- before those arrive fails to resolve. Gate on `onLoaded`, and wire the matching
258
- `*Result` callback — it carries the reason (`No field value found at path …`),
259
- which is otherwise invisible.
260
-
261
- The subcomponents report subsets of this set — see
262
- [subcomponents](./docs/validation-station-subcomponents.md).
322
+ | `onExtractionResultChanged` | Any change to the extraction result — needs `options={{ emitDtoStateChanges: true }}` |
323
+ | `onLoaded` | The element finished loading |
324
+ | `onDirtyChange` | Unsaved changes appear or are cleared |
325
+ | `onIsValidChange` | Validity flips (`true` = no Must rule broken, no invalid values) |
326
+ | `onDocumentTypeChanged` | The user picks another document type |
327
+ | `onFieldValueSelected` | The user selects a field value |
328
+ | `onFieldValueChanged` | The user edits a field value |
329
+ | `onBusinessRulesEvaluated` | Validation errors and business rules are re-evaluated |
330
+ | `onSaveResult` | A `save` command completes |
331
+ | `onSetFieldValueByPathResult` | A `setFieldValueByPath` command completes |
332
+ | `onSelectAndFocusFieldValueByPathResult` | A `selectAndFocusFieldValueByPath` command completes |
333
+ | `onDeleteFieldValueByPathResult` | A `deleteFieldValueByPath` command completes |
334
+ | `onFieldsPanelWidthChanged` | The fields panel is resized (width in px) |
335
+ | `onFieldsPanelSideChanged` | The panel moves to the other side of the viewer |
336
+ | `onWcMessage` | The element publishes a message on its bus (`ui-du-vs-wc-message`) — see below |
337
+
338
+ > **Attention: Commands need a loaded document**
339
+ > `setFieldValueByPath`, `selectAndFocusFieldValueByPath` and `deleteFieldValueByPath` resolve their `path` against the taxonomy and the current extraction result, so one issued before those arrive fails to resolve. Gate on `onLoaded`, and wire the matching `*Result` callback — it carries the reason (`No field value found at path …`), which is otherwise invisible.
340
+
341
+ The subcomponents report subsets of this set — see [subcomponents](https://github.com/UiPath/uipath-ui-widgets/blob/develop/packages/validation-station/docs/validation-station-subcomponents.md).
342
+
343
+ ### Rendering your own value-indicator overlay
344
+
345
+ Hovering a value's confidence indicator opens a built-in popover. `onWcMessage` receives an `IVsWcMessage`, discriminated on `type`: `indicator-overlay-show` carries the value's confidence, thresholds, confirmation and broken-rule state (`IVsIndicatorOverlayContext`) plus the trigger's viewport rect to position against, and `indicator-overlay-hide` closes it. Hide the built-in popover with CSS, then render your own:
346
+
347
+ ```css
348
+ ui-du-validation-station-standalone-wc-element::part(indicator-overlay) {
349
+ display: none;
350
+ }
351
+ ```
352
+
353
+ ```tsx
354
+ <ValidationStation
355
+ sdk={sdk}
356
+ data={data}
357
+ onWcMessage={(message) => {
358
+ if (message.type === "indicator-overlay-show") showPopover(message.context);
359
+ else hidePopover();
360
+ }}
361
+ />
362
+ ```
363
+
364
+ `message.instanceId` tells elements apart when several report to one handler. `CompactFieldsForm`, `CompactTableEditor` and `CompactBusinessRules` take `onWcMessage` too.
263
365
 
264
366
  ## Language enum
265
367
 
@@ -300,8 +402,21 @@ import type {
300
402
  ValidationStationProps,
301
403
  ValidationStationWcConfig,
302
404
  DuArtifactsSource,
405
+ ValidationStationArtifactsSource,
303
406
  DuDocumentArtifacts,
407
+ IxpDocumentArtifacts,
408
+ ValidationStationArtifacts,
409
+ IXPTaxonomy,
410
+ IXPExtraction,
411
+ ProcessedDocument,
412
+ IVsWcMessage,
304
413
  IValidationStationOptions,
414
+ FieldFilterOptions,
415
+ DocumentViewerOptions,
416
+ ICustomizationInfoDTO,
417
+ IFeatureCustomization,
418
+ IVsWcMessage,
419
+ IVsIndicatorOverlayContext,
305
420
  IVsSaveValidatedDataRequest,
306
421
  IVsSaveValidatedDataAsDraftRequest,
307
422
  IVsSaveExceptionReportRequest,
@@ -321,9 +436,7 @@ import type {
321
436
  } from "@uipath/ui-widgets-validation-station";
322
437
  ```
323
438
 
324
- `DU_WC_TAGS` and `VALIDATION_STATION_TAG` are the custom-element tag names the
325
- loader registers — useful for `document.querySelector` or asserting readiness in
326
- tests. The wrappers in this package render them for you.
439
+ `DU_WC_TAGS` and `VALIDATION_STATION_TAG` are the custom-element tag names the loader registers — useful for `document.querySelector` or asserting readiness in tests. The wrappers in this package render them for you.
327
440
 
328
441
  ## Examples
329
442
 
@@ -331,7 +444,8 @@ tests. The wrappers in this package render them for you.
331
444
 
332
445
  Address fields by path when you have nested groups or table rows. Each segment is `{ fieldName, valueIndex }`.
333
446
 
334
- > A path only resolves once the document has loaded — see [Reading the document state](#reading-the-document-state). Wire `onSetFieldValueByPathResult` while you are building this, or a mistimed command fails silently.
447
+ > **Note: Paths resolve only after the document loads**
448
+ > See [Reading the document state](#reading-the-document-state). Wire `onSetFieldValueByPathResult` while you are building this, or a mistimed command fails silently.
335
449
 
336
450
  ```tsx
337
451
  import { useState } from "react";
@@ -390,8 +504,8 @@ function App({ sdk, data }) {
390
504
  onClick={() =>
391
505
  setFocus({
392
506
  path: [
393
- { fieldName: "Invoice", valueIndex: 0 }, // parent field name
394
- { fieldName: "Amount", valueIndex: 0 }, // child field name
507
+ { fieldName: "Invoice", valueIndex: 0 },
508
+ { fieldName: "Amount", valueIndex: 0 },
395
509
  ],
396
510
  })
397
511
  }
@@ -419,37 +533,26 @@ const [save, setSave] = useState<{ validate: boolean } | undefined>(undefined);
419
533
 
420
534
  ## Hosting the web component
421
535
 
422
- The widgets in this package render the Validation Station **web component**, which
423
- ships as a prebuilt Angular bundle in
424
- [`@uipath/du-validation-station-wc`](https://www.npmjs.com/package/@uipath/du-validation-station-wc).
425
- The bundle is **not** imported by this package — it is loaded at runtime from a URL
426
- you host, via [`@uipath/du-utils`](https://www.npmjs.com/package/@uipath/du-utils).
536
+ The widgets in this package render the Validation Station **web component**, which ships as a prebuilt Angular bundle in [`@uipath/du-validation-station-wc`](https://www.npmjs.com/package/@uipath/du-validation-station-wc). The bundle is **not** imported by the package — it is loaded at runtime from a URL you host, via [`@uipath/du-utils`](https://www.npmjs.com/package/@uipath/du-utils).
427
537
 
428
538
  That means there is no bundler configuration to write. You need two things:
429
539
 
430
- 1. Serve the contents of `node_modules/@uipath/du-validation-station-wc` as static
431
- files at `du-vs-wc`, next to your app's own root (see the default below —
432
- pass an explicit `deploymentUrl` if you host it somewhere else).
540
+ 1. Serve the contents of `node_modules/@uipath/du-validation-station-wc` as static files at `du-vs-wc`, next to your app's own root (see the default below — pass an explicit `deploymentUrl` if you host it somewhere else).
433
541
  2. Call `configureValidationStationWc` once, before rendering any widget.
434
542
 
435
543
  ```ts
436
544
  import { configureValidationStationWc } from "@uipath/ui-widgets-validation-station";
437
545
 
438
546
  configureValidationStationWc({
439
- // Set true unless your app already loads Apollo fonts + Material Icons
440
- // globally — otherwise icon glyphs render as empty boxes.
547
+ // Set true unless your app already loads Material Icons globally —
548
+ // otherwise every icon renders as its ligature text. See "Fonts" below.
441
549
  includeFonts: true,
442
550
  }).catch((error) => {
443
551
  console.error("Validation Station web component failed to load", error);
444
552
  });
445
553
  ```
446
554
 
447
- `deploymentUrl` defaults to `du-vs-wc` joined onto
448
- [`getAppBase()`](https://www.npmjs.com/package/@uipath/uipath-typescript) —
449
- `/du-vs-wc` on a plain host, or the deployed app's own base path if you're
450
- running as a UiPath Coded App. Most integrations need nothing more than the
451
- call above. Pass an explicit `deploymentUrl` only when the web component is
452
- hosted somewhere that default doesn't reach:
555
+ `deploymentUrl` defaults to `du-vs-wc` joined onto `getAppBase()` — `/du-vs-wc` on a plain host, or the deployed app's own base path if you are running as a UiPath Coded App. Most integrations need nothing more than the call above. Pass an explicit `deploymentUrl` only when the web component is hosted somewhere that default doesn't reach:
453
556
 
454
557
  ```ts
455
558
  import {
@@ -467,71 +570,116 @@ configureValidationStationWc({
467
570
  });
468
571
  ```
469
572
 
470
- `joinDeploymentUrl(base, path)` exists because hand-rolled string
471
- concatenation is an easy way to end up with a doubled or missing slash — it
472
- strips any trailing slash from `base` and any leading slash from `path` before
473
- joining them, regardless of which one supplied it (or neither).
573
+ `joinDeploymentUrl(base, path)` exists because hand-rolled string concatenation is an easy way to end up with a doubled or missing slash — it strips any trailing slash from `base` and any leading slash from `path` before joining them, regardless of which one supplied it (or neither).
474
574
 
475
- The served directory must keep the package's own layout, because the bundle
476
- resolves these against its own `import.meta.url`:
575
+ The served directory must keep the package's own layout, because the bundle resolves these against its own `import.meta.url`:
477
576
 
478
577
  ```
479
578
  /du-vs-wc/
480
579
  ├── main.js ← entry, plus its hashed chunk-*.js siblings
481
- ├── polyfills.js ← zone.js; must load before main.js (the loader handles ordering)
580
+ ├── polyfills.js ← must load before main.js (the loader handles ordering)
482
581
  ├── styles.css ← fetched as raw CSS and adopted into the shadow root
483
- ├── fonts.css ← Apollo fonts + Material Icons (opt-in via includeFonts)
582
+ ├── fonts.css ← Material Icons only (opt-in via includeFonts)
484
583
  ├── media/ ← the font files fonts.css references
485
584
  └── du-assets/ ← pdf.js scripts, cmaps, wasm decoders, translations,
486
585
  the business-rules executor
487
586
  ```
488
587
 
489
- Copying the package directory verbatim satisfies this. In this repo, that is
490
- `npm run stage-du-wc` (see `scripts/copy-du-wc-assets.mjs`), wired to `predev`,
491
- which stages it into the gitignored `public/du-vs-wc`.
588
+ Copying the package directory verbatim satisfies this.
589
+
590
+ ### Serving it with Vite
591
+
592
+ > **Success: No `vite.config.ts` changes are needed**
593
+ > Since `1.1.0` the web component is fetched at runtime instead of imported, so it never enters the module graph. The `optimizeDeps.exclude`, asset-copy plugin and dev-server middleware that `1.0.x` required are all obsolete — delete them (see [Migrating from 1.0.x](#migrating-from-10x)). A Vite app needs nothing in its config beyond whatever it already has.
594
+
595
+ What it does need is the package copied into `public/`, which Vite serves verbatim in dev and copies to `dist/` on build. The four samples below all do it with one script wired to the `predev` and `prebuild` hooks, so a plain `npm run dev` or `npm run build` stages it:
596
+
597
+ ```json title="package.json"
598
+ {
599
+ "scripts": {
600
+ "stage-du-wc": "node scripts/stage-du-wc.mjs",
601
+ "predev": "npm run stage-du-wc",
602
+ "prebuild": "npm run stage-du-wc"
603
+ },
604
+ "devDependencies": {
605
+ "@uipath/du-validation-station-wc": "1.0.0-rc.3"
606
+ }
607
+ }
608
+ ```
609
+
610
+ The script copies `node_modules/@uipath/du-validation-station-wc` to `public/du-vs-wc` — which is exactly where the `deploymentUrl` default looks — skipping the npm metadata, verifying that `main.js`, `polyfills.js`, `styles.css`, `fonts.css` and `du-assets/` all landed, and stamping the staged version so a repeat run is a no-op. Take it as-is: [`scripts/stage-du-wc.mjs`](https://github.com/UiPath/uipath-typescript/blob/main/samples/document-validation-app/scripts/stage-du-wc.mjs).
611
+
612
+ > **Tip: Keep `public/du-vs-wc` out of git**
613
+ > It is generated, and it is tens of megabytes — the fonts alone are most of it. Add it to `.gitignore` and let the `predev` / `prebuild` hooks produce it.
614
+
615
+ ### Fonts
616
+
617
+ The `fonts.css` in `@uipath/du-validation-station-wc` carries **Material Icons
618
+ only** — the one font the component cannot do without. The Apollo text fonts
619
+ (Poppins, Noto Sans, Inconsolata) are not in the package, so the component's
620
+ text inherits your app's own font stack. A UiPath-styled host already loads
621
+ them; to get the UiPath typography otherwise, install
622
+ [`@uipath/apollo-fonts`](https://www.npmjs.com/package/@uipath/apollo-fonts) and
623
+ import its `font.css` in your app. That file contains Material Icons as well, so
624
+ `includeFonts` can then stay off.
625
+
626
+ A UiPath-hosted deployment of the web component is built with the full font set,
627
+ so `includeFonts: true` against one of those links the Apollo fonts too.
492
628
 
493
629
  ### Notes
494
630
 
495
- - **Call it once.** Loading is cached per page, so a second call with a different
496
- `deploymentUrl` is ignored. A _failed_ load is not cached — call again to retry.
497
- - **The returned promise is the error channel.** Components only observe success;
498
- a bad URL or a 404 surfaces on the promise, so attach a `.catch`. Without it, a
499
- load failure leaves the widgets showing their loading state.
500
- - **`du-assets/` and `media/` are outside that promise.** The loader only ever
501
- touches `polyfills.js`, `main.js`, `styles.css` and `fonts.css`; the web
502
- component fetches those two directories itself, at render time. Without
503
- `du-assets/`, PDF rendering and translations 404 silently while business-rules
504
- validation rejects outright — its executor is pulled in with a dynamic
505
- `import()`, so it fails loudly where the rest degrades quietly. Without
506
- `media/`, `fonts.css` resolves but every `url()` inside it 404s, so
507
- `includeFonts: true` loads no fonts.
508
- - **`deploymentUrl` accepts a resolver.** Pass `() => string | Promise<string>`
509
- instead of a plain string for cases where the URL isn't known synchronously —
510
- it's called lazily, at most once per load.
511
- - **`deploymentUrl` is a script source.** The loader injects
512
- `<script type="module" src>` from it, so whoever controls the URL executes code
513
- in your app's origin. Pass a literal, a build-time constant, or a resolver
514
- derived from one of those — never a value from `location`, a query parameter,
515
- or other user input.
516
- - **CSP.** Serving from your own origin needs no more than `script-src 'self'`.
517
- A separate origin must be added to `script-src` and `style-src`, and note that
518
- the loader offers no Subresource Integrity hook — self-hosting avoids that
519
- exposure entirely.
520
- - **Version skew.** The URL decides which web component version actually runs, and
521
- it is not checked against the installed `@uipath/du-validation-station-wc`. Keep
522
- the hosted copy in step with the version this package's types are built against.
631
+ - **Call it once.** Loading is cached per page, so a second call with a different `deploymentUrl` is ignored. A _failed_ load is not cached — call again to retry.
632
+ - **The returned promise is the error channel.** Components only observe success; a bad URL or a 404 surfaces on the promise, so attach a `.catch`. Without it, a load failure leaves the widgets showing their loading state.
633
+ - **`du-assets/` and `media/` are outside that promise.** The loader only ever touches `polyfills.js`, `main.js`, `styles.css` and `fonts.css`; the web component fetches those two directories itself, at render time. Without `du-assets/`, PDF rendering and translations 404 silently while business-rules validation rejects outright — its executor is pulled in with a dynamic `import()`, so it fails loudly where the rest degrades quietly. Without `media/`, `fonts.css` resolves but every `url()` inside it 404s, so `includeFonts: true` loads no fonts.
634
+ - **`deploymentUrl` accepts a resolver.** Pass `() => string | Promise<string>` instead of a plain string for cases where the URL isn't known synchronously — it is called lazily, at most once per load.
635
+ - **`deploymentUrl` is a script source.** The loader injects `<script type="module" src>` from it, so whoever controls the URL executes code in your app's origin. Pass a literal, a build-time constant, or a resolver derived from one of those — never a value from `location`, a query parameter, or other user input.
636
+ - **CSP.** Serving from your own origin needs no more than `script-src 'self'`. A separate origin must be added to `script-src` and `style-src`, and note that the loader offers no Subresource Integrity hook — self-hosting avoids that exposure entirely.
637
+ - **Version skew.** The URL decides which web component version actually runs, and it is not checked against the installed `@uipath/du-validation-station-wc`. Keep the hosted copy in step with the version this package's types are built against.
638
+
639
+ ## Web component 1.0.0-rc.3
640
+
641
+ The widgets now render `@uipath/du-validation-station-wc` `1.0.0-rc.3`. Keep the
642
+ hosted copy in step (see _Version skew_ above). No prop of this package was
643
+ removed or renamed, but the web component changes a few things you will see.
644
+
645
+ From rc.3:
646
+
647
+ - **The IXP representation.** `ValidationStation` takes an IXP document — a
648
+ Flow `processedDocument`, or `IxpDocumentArtifacts` — see
649
+ [IXP documents](#ixp-documents-processeddocument).
650
+ - **`HideHighlightRow`** on `FeatureCustomization` (compact mode) hides the
651
+ _Highlight row_ action from each field group row's menu.
652
+ - The compact fields form's expand / collapse-all control is redesigned, and
653
+ reads _Expand all field groups_ / _Collapse all field groups_.
654
+
655
+ From rc.2:
656
+
657
+ - **New compact UI, on by default:** a field-filter toolbar (trim or remove it
658
+ with `options.fieldFilterOptions`), expandable field groups, a line-number
659
+ column in the table editor, and a _Waiting for input_ screen until the
660
+ document data arrives.
661
+ - **`HideConfidence` now applies in compact mode too**, and is deprecated in
662
+ favour of `IgnoreConfidence` (either one takes confidence out of the
663
+ experience). A `customizationInfo` that already sets it will now hide the
664
+ confidence indicator in compact.
665
+ - **`fonts.css` carries Material Icons only** — see [Fonts](#fonts).
666
+ - **New options:** `fieldFilterOptions`, `defaultFieldsAreaPercentage` /
667
+ `defaultFieldsAreaWidth`, and `documentViewerOptions` for the embedded viewer
668
+ (with the new `hideExtractedTokensToggle` / `hideLanguageSelect` flags).
669
+ - **New outputs and inputs on this package:** `onWcMessage` (see
670
+ [Rendering your own value-indicator overlay](#rendering-your-own-value-indicator-overlay))
671
+ and `predictedExtractionResult` (see
672
+ [Comparing against the prediction](#comparing-against-the-prediction)).
673
+ - **`@uipath/uipath-typescript` `>= 1.5.1`** is now required — the web component
674
+ declares it as a peer dependency.
523
675
 
524
676
  ## Migrating from 1.0.x
525
677
 
526
678
  Four things changed since `1.0.1`, ordered by how loudly they fail.
527
679
 
528
- ### The web component now loads from a URL
680
+ <!-- details warning: The web component now loads from a URL -->
529
681
 
530
- `1.0.x` imported the web component as a bare module specifier, which put a
531
- prebuilt Angular bundle into your module graph and made its assets your
532
- bundler's problem. It now loads at runtime from a hosted URL, so you must call
533
- `configureValidationStationWc` once before rendering any widget from this
534
- package:
682
+ `1.0.x` imported the web component as a bare module specifier, which put a prebuilt Angular bundle into your module graph and made its assets your bundler's problem. It now loads at runtime from a hosted URL, so you must call `configureValidationStationWc` once before rendering any widget from this package:
535
683
 
536
684
  ```diff
537
685
  + import { configureValidationStationWc } from "@uipath/ui-widgets-validation-station";
@@ -539,24 +687,18 @@ package:
539
687
  + configureValidationStationWc();
540
688
  ```
541
689
 
542
- Miss it and nothing renders. See [Hosting the web component](#hosting-the-web-component)
543
- for the `deploymentUrl` default and when to override it.
690
+ Miss it and nothing renders. See [Hosting the web component](#hosting-the-web-component) for the `deploymentUrl` default and when to override it.
544
691
 
545
- **Delete your 1.0.x bundler setup.** None of it applies any more, and what it
546
- produces is no longer read:
692
+ **Delete your 1.0.x bundler setup.** None of it applies any more, and what it produces is no longer read:
547
693
 
548
694
  - the build-time `du-assets` / `media` / CSS copy plugin
549
695
  - `optimizeDeps.exclude` for `@uipath/du-validation-station-wc`
550
- - any dev-server middleware that intercepted the component's raw
551
- `fetch("styles.css")` by sniffing `Sec-Fetch-Dest`
696
+ - any dev-server middleware that intercepted the component's raw `fetch("styles.css")` by sniffing `Sec-Fetch-Dest`
697
+ <!-- /details -->
552
698
 
553
- ### Save callbacks are unified
699
+ <!-- details warning: Save callbacks are unified -->
554
700
 
555
- `1.0.x` had one pair of callbacks meaning "the widget persisted it" and another
556
- meaning "over to you", chosen by an unrelated input. There is now one callback
557
- per user action. It always carries the request, and takes the outcome as an
558
- optional second argument, present exactly when the widget did the write-back
559
- itself:
701
+ `1.0.x` had one pair of callbacks meaning "the widget persisted it" and another meaning "over to you", chosen by an unrelated input. There is now one callback per user action. It always carries the request, and takes the outcome as an optional second argument, present exactly when the widget did the write-back itself:
560
702
 
561
703
  ```diff
562
704
  - onSubmitComplete={(result) => …}
@@ -569,24 +711,15 @@ itself:
569
711
  + onReportException={(request) => …}
570
712
  ```
571
713
 
572
- > **Check the first parameter, not just the name.** The old callbacks took the
573
- > result first, the new ones take the request. A rename that leaves the body
574
- > alone reads `success` off the wrong object — and does it silently wherever the
575
- > handler isn't type-checked.
714
+ **Check the first parameter, not just the name.** The old callbacks took the result first, the new ones take the request. A rename that leaves the body alone reads `success` off the wrong object — and does it silently wherever the handler isn't type-checked.
576
715
 
577
- `onReportException` no longer receives `(documentId, reason)`; the reason is at
578
- `request.exceptionReport.Reason`. The widget still never persists that flow, so
579
- it has no `result` argument at all.
716
+ `onReportException` no longer receives `(documentId, reason)`; the reason is at `request.exceptionReport.Reason`. The widget still never persists that flow, so it has no `result` argument at all.
580
717
 
581
- The full contract is in
582
- [Reacting to save / draft / exception flows](#reacting-to-save--draft--exception-flows).
718
+ <!-- /details -->
583
719
 
584
- ### The folder comes from `ContentValidationData`
720
+ <!-- details warning: The folder comes from `ContentValidationData` -->
585
721
 
586
- The `folderId` prop is gone. The folder now travels on `ContentValidationData`
587
- itself, as `FolderId` or `FolderKey` — the activity that produces the payload
588
- sets one of them, so in the common case there is nothing to pass and nothing to
589
- wire up.
722
+ The `folderId` prop is gone. The folder now travels on `ContentValidationData` itself, as `FolderId` or `FolderKey` — the activity that produces the payload sets one of them, so in the common case there is nothing to pass and nothing to wire up.
590
723
 
591
724
  ```diff
592
725
  - <ValidationStation sdk={sdk} data={data} folderId={folderId} />
@@ -606,14 +739,11 @@ The four exported helpers lost the same parameter:
606
739
  + saveValidatedDataAsDraft(sdk, data, request)
607
740
  ```
608
741
 
609
- The activity that produces a `ContentValidationData` should normally set
610
- `FolderId` or `FolderKey`. If you construct the object yourself, set one of them
611
- accordingly — for example from the Action Center task's folder, which the SDK
612
- surfaces as `task.folderId` (`OrganizationUnitId` in Orchestrator). Memoise the
613
- object you pass in, or the widget takes a new reference on every render and
614
- refetches the document each time.
742
+ If you construct the object yourself, set `FolderId` or `FolderKey` — for example from the Action Center task's folder, which the SDK surfaces as `task.folderId`. Memoise the object you pass in, or the widget takes a new reference on every render and refetches the document each time.
615
743
 
616
- ### Renamed exports
744
+ <!-- /details -->
745
+
746
+ <!-- details note: Renamed exports -->
617
747
 
618
748
  Same shapes, new names — a find-and-replace:
619
749
 
@@ -624,13 +754,36 @@ Same shapes, new names — a find-and-replace:
624
754
  | `SubcomponentDataSource` | `DuArtifactsSource` |
625
755
  | `SubcomponentStateEventProps` | `VsStateEventProps` |
626
756
 
627
- ### Nothing to do
757
+ <!-- /details -->
758
+
759
+ <!-- details note: Nothing to do -->
760
+
761
+ `sdk` and `data` became optional, alongside the new `artifacts` / `documentId` props — existing calls that pass both keep working. See [Data sources](#data-sources). `ValidationStation` also gained `persistent` plus fourteen state, command-result and panel callbacks; all are additive.
762
+
763
+ <!-- /details -->
764
+
765
+ ## Sample apps
766
+
767
+ Four runnable apps in this repository use the widget end to end — task fetch, render, submit and completion. Each has a `README.md` with setup steps and a preview GIF; all four are also in the [Sample Apps Gallery](https://uipath.github.io/uipath-typescript/samples/).
768
+
769
+ | Sample | What it shows |
770
+ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
771
+ | [`document-validation-app`](https://github.com/UiPath/uipath-typescript/tree/main/samples/document-validation-app) | A standalone validation inbox: lists Action Center Document Validation tasks as Pending / Unassigned / Completed tabs and reviews the selected one with the all-in-one `ValidationStation` component |
772
+ | [`document-validation-subcomponents-app`](https://github.com/UiPath/uipath-typescript/tree/main/samples/document-validation-subcomponents-app) | The same review screen built from the package's five subcomponents in a custom grid, linked by one shared `instanceId` — the path to take when the standard layout does not fit |
773
+ | [`coded-action-apps/action-app-with-document-validation`](https://github.com/UiPath/uipath-typescript/tree/main/samples/coded-action-apps/action-app-with-document-validation) | The same widget as a [Coded Action App](https://uipath.github.io/uipath-typescript/coded-action-apps/getting-started/): no task list, Action Center routes the reviewer straight to one action |
774
+ | [`coded-action-apps/action-app-with-document-validation-subcomponents`](https://github.com/UiPath/uipath-typescript/tree/main/samples/coded-action-apps/action-app-with-document-validation-subcomponents) | The subcomponent layout as a Coded Action App |
775
+
776
+ All four stage the web component with the script described in [Serving it with Vite](#serving-it-with-vite).
628
777
 
629
- `sdk` and `data` became optional, alongside the new `artifacts` / `documentId`
630
- props — existing calls that pass both keep working. See
631
- [Data sources](#data-sources). `ValidationStation` also gained `persistent` and
632
- the fourteen state, command-result and panel callbacks the compact
633
- subcomponents already had; all are additive.
778
+ ## TypeScript
779
+
780
+ This package is written in TypeScript and ships its own type definitions — prop types are exported for use in your own component signatures:
781
+
782
+ ```tsx
783
+ import type { ValidationStationProps } from "@uipath/ui-widgets-validation-station";
784
+ ```
785
+
786
+ <!-- docs:ignore -->
634
787
 
635
788
  ## Development
636
789
 
@@ -644,3 +797,9 @@ npm run test
644
797
  # Run tests in watch mode
645
798
  npm run test:watch
646
799
  ```
800
+
801
+ ## License
802
+
803
+ MIT
804
+
805
+ <!-- /docs:ignore -->