@uipath/ui-widgets-validation-station 1.0.1-beta.7 → 1.1.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 (93) hide show
  1. package/README.md +388 -127
  2. package/dist/ValidationStation.d.ts +12 -0
  3. package/dist/ValidationStation.d.ts.map +1 -1
  4. package/dist/ValidationStation.js +72 -49
  5. package/dist/ValidationStation.js.map +1 -1
  6. package/dist/ValidationStation.stories.d.ts.map +1 -1
  7. package/dist/ValidationStation.stories.js +30 -19
  8. package/dist/ValidationStation.stories.js.map +1 -1
  9. package/dist/bindWcEvents.d.ts +25 -0
  10. package/dist/bindWcEvents.d.ts.map +1 -0
  11. package/dist/bindWcEvents.js +59 -0
  12. package/dist/bindWcEvents.js.map +1 -0
  13. package/dist/bucketArtifactsUtil.d.ts +13 -3
  14. package/dist/bucketArtifactsUtil.d.ts.map +1 -1
  15. package/dist/bucketArtifactsUtil.js +50 -33
  16. package/dist/bucketArtifactsUtil.js.map +1 -1
  17. package/dist/index.d.ts +14 -1
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +13 -0
  20. package/dist/index.js.map +1 -1
  21. package/dist/loadValidationStationWc.d.ts +73 -4
  22. package/dist/loadValidationStationWc.d.ts.map +1 -1
  23. package/dist/loadValidationStationWc.js +104 -9
  24. package/dist/loadValidationStationWc.js.map +1 -1
  25. package/dist/saveHandlers.d.ts +19 -0
  26. package/dist/saveHandlers.d.ts.map +1 -0
  27. package/dist/saveHandlers.js +41 -0
  28. package/dist/saveHandlers.js.map +1 -0
  29. package/dist/saveValidatedDataUtil.d.ts +2 -2
  30. package/dist/saveValidatedDataUtil.d.ts.map +1 -1
  31. package/dist/saveValidatedDataUtil.js +32 -22
  32. package/dist/saveValidatedDataUtil.js.map +1 -1
  33. package/dist/subcomponents/CompactBusinessRules.d.ts +8 -0
  34. package/dist/subcomponents/CompactBusinessRules.d.ts.map +1 -0
  35. package/dist/subcomponents/CompactBusinessRules.js +55 -0
  36. package/dist/subcomponents/CompactBusinessRules.js.map +1 -0
  37. package/dist/subcomponents/CompactDocTypeField.d.ts +8 -0
  38. package/dist/subcomponents/CompactDocTypeField.d.ts.map +1 -0
  39. package/dist/subcomponents/CompactDocTypeField.js +42 -0
  40. package/dist/subcomponents/CompactDocTypeField.js.map +1 -0
  41. package/dist/subcomponents/CompactFieldsForm.d.ts +10 -0
  42. package/dist/subcomponents/CompactFieldsForm.d.ts.map +1 -0
  43. package/dist/subcomponents/CompactFieldsForm.js +68 -0
  44. package/dist/subcomponents/CompactFieldsForm.js.map +1 -0
  45. package/dist/subcomponents/CompactTableEditor.d.ts +11 -0
  46. package/dist/subcomponents/CompactTableEditor.d.ts.map +1 -0
  47. package/dist/subcomponents/CompactTableEditor.js +61 -0
  48. package/dist/subcomponents/CompactTableEditor.js.map +1 -0
  49. package/dist/subcomponents/DocumentViewer.d.ts +8 -0
  50. package/dist/subcomponents/DocumentViewer.d.ts.map +1 -0
  51. package/dist/subcomponents/DocumentViewer.js +52 -0
  52. package/dist/subcomponents/DocumentViewer.js.map +1 -0
  53. package/dist/subcomponents/shared.d.ts +35 -0
  54. package/dist/subcomponents/shared.d.ts.map +1 -0
  55. package/dist/subcomponents/shared.js +36 -0
  56. package/dist/subcomponents/shared.js.map +1 -0
  57. package/dist/subcomponents/types.d.ts +82 -0
  58. package/dist/subcomponents/types.d.ts.map +1 -0
  59. package/dist/subcomponents/types.js +2 -0
  60. package/dist/subcomponents/types.js.map +1 -0
  61. package/dist/subcomponents/useWcElement.d.ts +43 -0
  62. package/dist/subcomponents/useWcElement.d.ts.map +1 -0
  63. package/dist/subcomponents/useWcElement.js +38 -0
  64. package/dist/subcomponents/useWcElement.js.map +1 -0
  65. package/dist/types.d.ts +153 -34
  66. package/dist/types.d.ts.map +1 -1
  67. package/dist/types.js +15 -0
  68. package/dist/types.js.map +1 -1
  69. package/dist/urlUtil.d.ts +9 -0
  70. package/dist/urlUtil.d.ts.map +1 -0
  71. package/dist/urlUtil.js +11 -0
  72. package/dist/urlUtil.js.map +1 -0
  73. package/dist/useDuDocumentArtifacts.d.ts +12 -0
  74. package/dist/useDuDocumentArtifacts.d.ts.map +1 -0
  75. package/dist/useDuDocumentArtifacts.js +11 -0
  76. package/dist/useDuDocumentArtifacts.js.map +1 -0
  77. package/dist/useResolvedArtifacts.d.ts +41 -0
  78. package/dist/useResolvedArtifacts.d.ts.map +1 -0
  79. package/dist/useResolvedArtifacts.js +85 -0
  80. package/dist/useResolvedArtifacts.js.map +1 -0
  81. package/dist/useWcReady.d.ts +12 -0
  82. package/dist/useWcReady.d.ts.map +1 -0
  83. package/dist/useWcReady.js +31 -0
  84. package/dist/useWcReady.js.map +1 -0
  85. package/dist/utils/telemetryUtils.d.ts +3 -0
  86. package/dist/utils/telemetryUtils.d.ts.map +1 -0
  87. package/dist/utils/telemetryUtils.js +10 -0
  88. package/dist/utils/telemetryUtils.js.map +1 -0
  89. package/package.json +6 -5
  90. package/dist/useBucketArtifacts.d.ts +0 -8
  91. package/dist/useBucketArtifacts.d.ts.map +0 -1
  92. package/dist/useBucketArtifacts.js +0 -39
  93. package/dist/useBucketArtifacts.js.map +0 -1
package/README.md CHANGED
@@ -13,7 +13,7 @@ npm install @uipath/ui-widgets-validation-station
13
13
  ```
14
14
  react >= 19.2.0
15
15
  react-dom >= 19.2.0
16
- @uipath/uipath-typescript >= 1.4.1
16
+ @uipath/uipath-typescript >= 1.4.2
17
17
  ```
18
18
 
19
19
  ## Quick start
@@ -22,12 +22,17 @@ react-dom >= 19.2.0
22
22
 
23
23
  ```tsx
24
24
  import {
25
+ configureValidationStationWc,
25
26
  ValidationStation,
26
27
  ValidationStationLanguage,
27
28
  } from "@uipath/ui-widgets-validation-station";
28
29
  import { UiPath } from "@uipath/uipath-typescript/core";
29
30
  import type { DuFramework } from "@uipath/uipath-typescript/document-understanding";
30
31
 
32
+ // Once, at app startup — loads the web component from `du-vs-wc`, next to
33
+ // your app's own root by default. See "Hosting the web component" below.
34
+ configureValidationStationWc();
35
+
31
36
  const sdk = new UiPath({
32
37
  baseUrl: "https://cloud.uipath.com",
33
38
  orgName: "your-org",
@@ -42,50 +47,140 @@ function App() {
42
47
  <ValidationStation
43
48
  sdk={sdk}
44
49
  data={selectedTask.data as DuFramework.ContentValidationData}
45
- folderId={12345}
46
50
  />
47
51
  );
48
52
  }
49
53
  ```
50
54
 
51
- > `theme` defaults to `"light"` and `language` defaults to `ValidationStationLanguage.English`, so the minimal mount just needs `sdk`, `data`, and a folder.
55
+ > `theme` defaults to `"light"` and `language` defaults to `ValidationStationLanguage.English`, so the minimal mount just needs `sdk` and `data`.
56
+
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).
61
+
62
+ ## Data sources
63
+
64
+ The widget needs a taxonomy, an extraction result and a document DOM. There are two mutually-exclusive ways to give it those:
65
+
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 |
70
+
71
+ **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
+
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`.
74
+
75
+ ```tsx
76
+ import {
77
+ ValidationStation,
78
+ type DuDocumentArtifacts,
79
+ } from "@uipath/ui-widgets-validation-station";
80
+
81
+ function App({ artifacts }: { artifacts: DuDocumentArtifacts }) {
82
+ return (
83
+ <ValidationStation
84
+ artifacts={artifacts}
85
+ documentId="doc-123"
86
+ onSubmit={(request) => persistItYourself(request)}
87
+ />
88
+ );
89
+ }
90
+ ```
91
+
92
+ Every bucket call is scoped to the folder `data` names — `FolderId`, or `FolderKey` when both are present. The activity that produces the `ContentValidationData` sets one of them; if neither is there, the widget renders an error instead of fetching.
52
93
 
53
- > See [Static assets](#static-assets) below — you must copy the WC's
54
- > `du-assets/` folder into your build output, or PDF rendering and
55
- > translations will silently 404 in production.
94
+ 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
+
96
+ > `DuDocumentArtifacts` is `{ taxonomy, extractionResult, dom, text, customizationInfo, original }` — `original` is the base64-encoded document the viewer renders.
97
+
98
+ ### Owning the round-trip
99
+
100
+ 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
+
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. |
108
+
109
+ ```tsx
110
+ import {
111
+ fetchDuDocumentArtifacts,
112
+ submitValidatedData,
113
+ saveValidatedDataAsDraft,
114
+ ValidationStation,
115
+ type DuDocumentArtifacts,
116
+ } from "@uipath/ui-widgets-validation-station";
117
+
118
+ function HostOwnedReview({ sdk, data }) {
119
+ const [artifacts, setArtifacts] = useState<DuDocumentArtifacts | null>(null);
120
+
121
+ useEffect(() => {
122
+ fetchDuDocumentArtifacts(sdk, data).then(setArtifacts);
123
+ }, [sdk, data]);
124
+
125
+ if (!artifacts) return <div>Loading document…</div>;
126
+
127
+ return (
128
+ <ValidationStation
129
+ artifacts={artifacts}
130
+ documentId={data.DocumentId}
131
+ // no sdk / data — the host loads and persists
132
+ onSubmit={async (request) => {
133
+ const result = await submitValidatedData(sdk, data, request);
134
+ afterSubmit(result);
135
+ }}
136
+ onSaveAsDraft={(request) => saveValidatedDataAsDraft(sdk, data, request)}
137
+ />
138
+ );
139
+ }
140
+ ```
141
+
142
+ > Handle **both** callbacks. The widget always offers "Save as draft", so leaving `onSaveAsDraft` unwired means a draft click persists nothing.
143
+
144
+ The request payloads are exported too — `IVsSaveValidatedDataRequest`, `IVsSaveValidatedDataAsDraftRequest` and `IVsSaveExceptionReportRequest` — so handlers declared outside JSX can name their parameter.
145
+
146
+ A full working example lives in the repo's sample app under `samples/pages/ValidationStation/ValidationStationPrefetchedPage.tsx`.
56
147
 
57
148
  ## Props
58
149
 
59
150
  | Prop | Type | Required | Default | Description |
60
151
  | -------------------------------- | ---------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61
- | `sdk` | `UiPath` | Yes | — | UiPath SDK instance for authentication and API calls |
62
- | `data` | `ContentValidationData` | Yes | — | Document data containing bucket paths, document ID, and folder references |
63
- | `folderId` | `number` | No\* | — | Storage bucket folder ID. Falls back to `data.FolderId`. **One of the two must resolve to a value** — otherwise the widget show an error. |
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` |
64
156
  | `theme` | `'light' \| 'dark' \| 'light-hc' \| 'dark-hc'` | No | `'light'` | Visual theme |
65
157
  | `language` | `ValidationStationLanguage` | No | `English` | UI language (see enum below) |
66
158
  | `isReadonly` | `boolean` | No | `false` | When `true`, renders in read-only mode |
67
- | `options` | `IValidationStationOptions` | No | — | Fine-grained UI feature flags |
68
- | `save={{ validate: false }}` | `{ validate: boolean }` | No | — | Trigger **save as draft**. ⚠ Requires `options.emitDtoStateChanges: true` — otherwise the WC won't surface the latest in-memory extraction state and the save will be a no-op. |
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** |
69
162
  | `save={{ validate: true }}` | `{ validate: boolean }` | No | — | Trigger **submit** — runs validation first, then saves. |
70
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. |
71
164
  | `setFieldValueByPath` | `SetFieldValueByPath` | No | — | Set a field value addressed by a path of `{ fieldName, valueIndex }` segments |
72
165
  | `selectAndFocusFieldValueByPath` | `SelectAndFocusFieldValueByPath` | No | — | Select and focus a field value addressed by a path; focuses the document reference if any |
73
166
  | `deleteFieldValueByPath` | `DeleteFieldValueByPath` | No | — | Delete a field value addressed by a path |
74
167
 
75
- > Three additional callback props (`onSubmitComplete`, `onSaveAsDraftComplete`, `onReportExceptionComplete`) are documented in the next section.
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).
76
169
 
77
170
  ### Reacting to save / draft / exception flows
78
171
 
79
- The widget surfaces three user-initiated flows. Submit and draft are owned end-to-end by the widget; exception reporting is forwarded to the host so it can call the SDK directly.
172
+ 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.
80
173
 
81
- | Callback | User action | Signature | What the widget does | What the host does |
82
- | --------------------------- | ----------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
83
- | `onSubmitComplete` | **Submit** | `(result: SaveValidatedDataResult) => void` | Calls `OrchestratorDuModule.processExtractedData(...)`, then uploads the merged result to `ValidatedExtractionResultsPath`. Fires the callback with the persistence result. | (optional) react to success/failure (complete the task, retry, log, etc.). |
84
- | `onSaveAsDraftComplete` | **Save as draft** | `(result: SaveValidatedDataResult) => void` | Uploads the in-progress `validatedData` straight to `ValidatedExtractionResultsPath` (no `processExtractedData` call). Fires the callback with the persistence result. | (optional) react to success/failure. |
85
- | `onReportExceptionComplete` | **Report as exception** | `(documentId: string, reason: string) => void` | Extracts `documentId` and `reason` from the WC's exception DTO and hands them to the host. **No API call.** | Required if you want the report persisted — call `OrchestratorDuModule.submitExceptionReport(...)` yourself. |
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. |
86
179
 
87
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.
88
181
 
182
+ All three fire on every user action, regardless of mode — that is the contract. Only `result` varies.
183
+
89
184
  ```tsx
90
185
  import {
91
186
  ValidationStation,
@@ -94,22 +189,24 @@ import {
94
189
  import { OrchestratorDuModule } from "@uipath/uipath-typescript/orchestrator-du-module";
95
190
 
96
191
  function App({ sdk, data, task }) {
97
- const handleSubmitComplete = async (result: SaveValidatedDataResult) => {
98
- if (!result.success) {
99
- console.warn("Submit failed:", result.error);
192
+ // `sdk` + `data` are set, so the widget persisted it and `result` is present.
193
+ const handleSubmit = async (request, result?: SaveValidatedDataResult) => {
194
+ if (!result?.success) {
195
+ console.warn("Submit failed:", result?.error);
100
196
  return;
101
197
  }
102
198
  await task.complete({ action: "Completed", type: "DocumentValidation" });
103
199
  };
104
200
 
105
- const handleDraftComplete = (result: SaveValidatedDataResult) => {
106
- if (!result.success) console.warn("Draft save failed:", result.error);
201
+ const handleSaveAsDraft = (request, result?: SaveValidatedDataResult) => {
202
+ if (!result?.success) console.warn("Draft save failed:", result?.error);
107
203
  };
108
204
 
109
- const handleReportException = async (documentId: string, reason: string) => {
205
+ const handleReportException = async (request) => {
206
+ const reason = request.exceptionReport?.Reason ?? "";
110
207
  const response = await new OrchestratorDuModule(sdk).submitExceptionReport(
111
208
  task.id,
112
- documentId,
209
+ request.documentId,
113
210
  reason || "Reported via Validation Station",
114
211
  { folderId: task.folderId },
115
212
  );
@@ -122,16 +219,47 @@ function App({ sdk, data, task }) {
122
219
  <ValidationStation
123
220
  sdk={sdk}
124
221
  data={data}
125
- folderId={task.folderId}
126
- onSubmitComplete={handleSubmitComplete}
127
- onSaveAsDraftComplete={handleDraftComplete}
128
- onReportExceptionComplete={handleReportException}
222
+ onSubmit={handleSubmit}
223
+ onSaveAsDraft={handleSaveAsDraft}
224
+ onReportException={handleReportException}
129
225
  />
130
226
  );
131
227
  }
132
228
  ```
133
229
 
134
- > Submit and draft callbacks are optional, but failures are silent if you skip them — the widget does not surface errors on its own. The exception callback is the only place the report goes; without it the user's "Report as exception" click is a no-op.
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.
231
+
232
+ ## Reading the document state
233
+
234
+ These callbacks report the rest of the element's
235
+ `IValidationStationStandaloneWcEventMap`; the three save flows are above.
236
+
237
+ | Prop | Fires when |
238
+ | ---------------------------------------- | ------------------------------------------------------------------------------------- |
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).
135
263
 
136
264
  ## Language enum
137
265
 
@@ -161,23 +289,50 @@ ValidationStationLanguage.ChineseTraditional; // "zh-TW"
161
289
  All parameter types are re-exported from the package for convenience:
162
290
 
163
291
  ```ts
164
- import { ValidationStationLanguage } from "@uipath/ui-widgets-validation-station";
292
+ import {
293
+ configureValidationStationWc,
294
+ DU_WC_TAGS,
295
+ joinDeploymentUrl,
296
+ VALIDATION_STATION_TAG,
297
+ ValidationStationLanguage,
298
+ } from "@uipath/ui-widgets-validation-station";
165
299
  import type {
166
300
  ValidationStationProps,
301
+ ValidationStationWcConfig,
302
+ DuArtifactsSource,
303
+ DuDocumentArtifacts,
167
304
  IValidationStationOptions,
305
+ IVsSaveValidatedDataRequest,
306
+ IVsSaveValidatedDataAsDraftRequest,
307
+ IVsSaveExceptionReportRequest,
168
308
  SaveValidatedDataResult,
169
309
  SetFieldValueByPath,
170
310
  SelectAndFocusFieldValueByPath,
171
311
  DeleteFieldValueByPath,
312
+ ValidationStationEventProps,
313
+ VsStateEventProps,
314
+ VsSaveResultEventProps,
315
+ IFieldValueDetailsDto,
316
+ EvaluatedBusinessRulesForFieldValueDto,
317
+ ISaveResult,
318
+ SetFieldValueByPathResult,
319
+ SelectAndFocusFieldValueByPathResult,
320
+ DeleteFieldValueByPathResult,
172
321
  } from "@uipath/ui-widgets-validation-station";
173
322
  ```
174
323
 
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.
327
+
175
328
  ## Examples
176
329
 
177
330
  ### Setting a field value by path
178
331
 
179
332
  Address fields by path when you have nested groups or table rows. Each segment is `{ fieldName, valueIndex }`.
180
333
 
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.
335
+
181
336
  ```tsx
182
337
  import { useState } from "react";
183
338
  import {
@@ -208,7 +363,6 @@ function App({ sdk, data }) {
208
363
  <ValidationStation
209
364
  sdk={sdk}
210
365
  data={data}
211
- folderId={67}
212
366
  setFieldValueByPath={fieldValueByPath}
213
367
  />
214
368
  </>
@@ -247,7 +401,6 @@ function App({ sdk, data }) {
247
401
  <ValidationStation
248
402
  sdk={sdk}
249
403
  data={data}
250
- folderId={67}
251
404
  selectAndFocusFieldValueByPath={focus}
252
405
  />
253
406
  </>
@@ -261,115 +414,223 @@ function App({ sdk, data }) {
261
414
  const [save, setSave] = useState<{ validate: boolean } | undefined>(undefined);
262
415
 
263
416
  <button onClick={() => setSave({ validate: true })}>Save</button>
264
- <ValidationStation sdk={sdk} data={data} folderId={1} save={save} />
417
+ <ValidationStation sdk={sdk} data={data} save={save} />
265
418
  ```
266
419
 
267
- ## Static assets
420
+ ## Hosting the web component
268
421
 
269
- The underlying web component loads runtime assets (PDF.js worker, cmaps,
270
- wasm, i18n translations) from a sibling `du-assets/` directory, resolved
271
- relative to where the WC's main bundle is served via `import.meta.url`.
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).
272
427
 
273
- **`du-assets/` must be deployed at the same path level as your output
274
- bundle**, otherwise PDF rendering and translations will silently 404 in
275
- the browser (no build error). You need to copy
276
- `node_modules/@uipath/du-validation-station-wc/du-assets/` into your
277
- build output as a post-build step.
428
+ That means there is no bundler configuration to write. You need two things:
278
429
 
279
- ### Vite
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).
433
+ 2. Call `configureValidationStationWc` once, before rendering any widget.
280
434
 
281
- Add a small plugin to `vite.config.ts` that copies `du-assets/` next to
282
- your emitted JS chunks after each build:
435
+ ```ts
436
+ import { configureValidationStationWc } from "@uipath/ui-widgets-validation-station";
437
+
438
+ configureValidationStationWc({
439
+ // Set true unless your app already loads Apollo fonts + Material Icons
440
+ // globally — otherwise icon glyphs render as empty boxes.
441
+ includeFonts: true,
442
+ }).catch((error) => {
443
+ console.error("Validation Station web component failed to load", error);
444
+ });
445
+ ```
446
+
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:
283
453
 
284
454
  ```ts
285
- // vite.config.ts
286
- import react from "@vitejs/plugin-react";
287
- import { cp } from "node:fs/promises";
288
- import { createRequire } from "node:module";
289
- import { dirname, resolve } from "node:path";
290
- import { defineConfig, type Plugin } from "vite";
291
-
292
- const require = createRequire(import.meta.url);
293
-
294
- function copyDuValidationStationAssets(): Plugin {
295
- let destDir = "";
296
- return {
297
- name: "copy-du-validation-station-assets",
298
- apply: "build",
299
- configResolved(config) {
300
- destDir = resolve(
301
- config.root,
302
- config.build.outDir,
303
- config.build.assetsDir,
304
- "du-assets",
305
- );
306
- },
307
- async closeBundle() {
308
- const wcRoot = dirname(
309
- require.resolve("@uipath/du-validation-station-wc/package.json"),
310
- );
311
- await cp(resolve(wcRoot, "du-assets"), destDir, { recursive: true });
312
- },
313
- };
314
- }
455
+ import {
456
+ configureValidationStationWc,
457
+ joinDeploymentUrl,
458
+ } from "@uipath/ui-widgets-validation-station";
315
459
 
316
- export default defineConfig({
317
- plugins: [react(), copyDuValidationStationAssets()],
318
- optimizeDeps: {
319
- exclude: ["@uipath/du-validation-station-wc"],
320
- },
460
+ configureValidationStationWc({
461
+ // A literal, a build-time constant, or a resolver — see "Notes" below.
462
+ deploymentUrl: joinDeploymentUrl(
463
+ "https://cdn.example.com/my-app",
464
+ "du-vs-wc",
465
+ ),
466
+ includeFonts: true,
321
467
  });
322
468
  ```
323
469
 
324
- `optimizeDeps.exclude` is required — Vite's pre-bundler rewrites
325
- `import.meta.url`, which breaks the WC's runtime asset resolution.
326
-
327
- ### webpack
328
-
329
- Use [`copy-webpack-plugin`](https://github.com/webpack-contrib/copy-webpack-plugin) **and** opt the WC bundle out of webpack's `new URL(..., import.meta.url)` parsing — the WC uses that pattern to load `du-assets/` at runtime, and webpack will otherwise try to bundle the directory and fail with `Module not found: Error: Can't resolve './du-assets/'`:
330
-
331
- ```js
332
- // webpack.config.js
333
- const CopyPlugin = require("copy-webpack-plugin");
334
- const path = require("path");
335
-
336
- module.exports = {
337
- module: {
338
- rules: [
339
- // Don't parse runtime URL / dynamic-require expressions inside the WC —
340
- // its assets are resolved at runtime from `import.meta.url`.
341
- {
342
- test: /node_modules[\\/]@uipath[\\/]du-validation-station-wc[\\/].*\.js$/,
343
- parser: {
344
- url: false,
345
- exprContextCritical: false,
346
- unknownContextCritical: false,
347
- },
348
- },
349
- ],
350
- },
351
- plugins: [
352
- new CopyPlugin({
353
- patterns: [
354
- {
355
- from:
356
- path.dirname(
357
- require.resolve("@uipath/du-validation-station-wc/package.json"),
358
- ) + "/du-assets",
359
- to: "assets/du-assets",
360
- },
361
- ],
362
- }),
363
- ],
364
- };
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).
474
+
475
+ The served directory must keep the package's own layout, because the bundle
476
+ resolves these against its own `import.meta.url`:
477
+
478
+ ```
479
+ /du-vs-wc/
480
+ ├── main.js ← entry, plus its hashed chunk-*.js siblings
481
+ ├── polyfills.js ← zone.js; must load before main.js (the loader handles ordering)
482
+ ├── styles.css ← fetched as raw CSS and adopted into the shadow root
483
+ ├── fonts.css ← Apollo fonts + Material Icons (opt-in via includeFonts)
484
+ ├── media/ ← the font files fonts.css references
485
+ └── du-assets/ ← pdf.js scripts, cmaps, wasm decoders, translations,
486
+ the business-rules executor
487
+ ```
488
+
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`.
492
+
493
+ ### Notes
494
+
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.
523
+
524
+ ## Migrating from 1.0.x
525
+
526
+ Four things changed since `1.0.1`, ordered by how loudly they fail.
527
+
528
+ ### The web component now loads from a URL
529
+
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:
535
+
536
+ ```diff
537
+ + import { configureValidationStationWc } from "@uipath/ui-widgets-validation-station";
538
+ +
539
+ + configureValidationStationWc();
540
+ ```
541
+
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.
544
+
545
+ **Delete your 1.0.x bundler setup.** None of it applies any more, and what it
546
+ produces is no longer read:
547
+
548
+ - the build-time `du-assets` / `media` / CSS copy plugin
549
+ - `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`
552
+
553
+ ### Save callbacks are unified
554
+
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:
560
+
561
+ ```diff
562
+ - onSubmitComplete={(result) => …}
563
+ - onSaveAsDraftComplete={(result) => …}
564
+ - onReportExceptionComplete={(documentId, reason) => …}
565
+ - onSaveValidatedDataRequest={(request) => …}
566
+ - onSaveValidatedDataAsDraftRequest={(request) => …}
567
+ + onSubmit={(request, result) => …}
568
+ + onSaveAsDraft={(request, result) => …}
569
+ + onReportException={(request) => …}
365
570
  ```
366
571
 
367
- ### Other bundlers
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.
576
+
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.
580
+
581
+ The full contract is in
582
+ [Reacting to save / draft / exception flows](#reacting-to-save--draft--exception-flows).
583
+
584
+ ### The folder comes from `ContentValidationData`
585
+
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.
590
+
591
+ ```diff
592
+ - <ValidationStation sdk={sdk} data={data} folderId={folderId} />
593
+ + <ValidationStation sdk={sdk} data={data} />
594
+ ```
595
+
596
+ The four exported helpers lost the same parameter:
597
+
598
+ ```diff
599
+ - fetchDuDocumentArtifacts(sdk, data, folderId)
600
+ - useDuDocumentArtifacts(sdk, data, folderId)
601
+ - submitValidatedData(sdk, data, folderId, request)
602
+ - saveValidatedDataAsDraft(sdk, data, folderId, request)
603
+ + fetchDuDocumentArtifacts(sdk, data)
604
+ + useDuDocumentArtifacts(sdk, data)
605
+ + submitValidatedData(sdk, data, request)
606
+ + saveValidatedDataAsDraft(sdk, data, request)
607
+ ```
608
+
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.
615
+
616
+ ### Renamed exports
617
+
618
+ Same shapes, new names — a find-and-replace:
619
+
620
+ | 1.0.x | Now |
621
+ | ----------------------------- | ------------------------ |
622
+ | `useBucketArtifacts` | `useDuDocumentArtifacts` |
623
+ | `BucketArtifacts` | `DuDocumentArtifacts` |
624
+ | `SubcomponentDataSource` | `DuArtifactsSource` |
625
+ | `SubcomponentStateEventProps` | `VsStateEventProps` |
626
+
627
+ ### Nothing to do
368
628
 
369
- Any asset-copy mechanism works — Angular's `assets` array,
370
- `rollup-plugin-copy`, a `postbuild` npm script with `cp -r`, etc. The
371
- only requirement is that the final deployed layout has `du-assets/`
372
- sitting next to the JS chunks that import the WC.
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.
373
634
 
374
635
  ## Development
375
636