@uipath/ui-widgets-validation-station 1.0.1 → 1.1.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 (73) hide show
  1. package/README.md +384 -191
  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/bucketArtifactsUtil.d.ts +13 -3
  10. package/dist/bucketArtifactsUtil.d.ts.map +1 -1
  11. package/dist/bucketArtifactsUtil.js +42 -32
  12. package/dist/bucketArtifactsUtil.js.map +1 -1
  13. package/dist/index.d.ts +9 -4
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +7 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/loadValidationStationWc.d.ts +59 -7
  18. package/dist/loadValidationStationWc.d.ts.map +1 -1
  19. package/dist/loadValidationStationWc.js +81 -20
  20. package/dist/loadValidationStationWc.js.map +1 -1
  21. package/dist/saveHandlers.d.ts +19 -0
  22. package/dist/saveHandlers.d.ts.map +1 -0
  23. package/dist/saveHandlers.js +41 -0
  24. package/dist/saveHandlers.js.map +1 -0
  25. package/dist/saveValidatedDataUtil.d.ts +2 -2
  26. package/dist/saveValidatedDataUtil.d.ts.map +1 -1
  27. package/dist/saveValidatedDataUtil.js +32 -22
  28. package/dist/saveValidatedDataUtil.js.map +1 -1
  29. package/dist/subcomponents/CompactFieldsForm.d.ts +4 -4
  30. package/dist/subcomponents/CompactFieldsForm.d.ts.map +1 -1
  31. package/dist/subcomponents/CompactFieldsForm.js +8 -27
  32. package/dist/subcomponents/CompactFieldsForm.js.map +1 -1
  33. package/dist/subcomponents/shared.d.ts +3 -3
  34. package/dist/subcomponents/shared.d.ts.map +1 -1
  35. package/dist/subcomponents/shared.js.map +1 -1
  36. package/dist/subcomponents/types.d.ts +8 -54
  37. package/dist/subcomponents/types.d.ts.map +1 -1
  38. package/dist/subcomponents/useWcElement.d.ts +5 -6
  39. package/dist/subcomponents/useWcElement.d.ts.map +1 -1
  40. package/dist/subcomponents/useWcElement.js +2 -4
  41. package/dist/subcomponents/useWcElement.js.map +1 -1
  42. package/dist/types.d.ts +150 -31
  43. package/dist/types.d.ts.map +1 -1
  44. package/dist/types.js +15 -0
  45. package/dist/types.js.map +1 -1
  46. package/dist/urlUtil.d.ts +9 -0
  47. package/dist/urlUtil.d.ts.map +1 -0
  48. package/dist/urlUtil.js +11 -0
  49. package/dist/urlUtil.js.map +1 -0
  50. package/dist/useDuDocumentArtifacts.d.ts +12 -0
  51. package/dist/useDuDocumentArtifacts.d.ts.map +1 -0
  52. package/dist/useDuDocumentArtifacts.js +11 -0
  53. package/dist/useDuDocumentArtifacts.js.map +1 -0
  54. package/dist/useResolvedArtifacts.d.ts +41 -0
  55. package/dist/useResolvedArtifacts.d.ts.map +1 -0
  56. package/dist/{useSubcomponentArtifacts.js → useResolvedArtifacts.js} +24 -26
  57. package/dist/useResolvedArtifacts.js.map +1 -0
  58. package/dist/useWcReady.d.ts +7 -3
  59. package/dist/useWcReady.d.ts.map +1 -1
  60. package/dist/useWcReady.js +11 -3
  61. package/dist/useWcReady.js.map +1 -1
  62. package/dist/utils/telemetryUtils.d.ts +3 -0
  63. package/dist/utils/telemetryUtils.d.ts.map +1 -0
  64. package/dist/utils/telemetryUtils.js +10 -0
  65. package/dist/utils/telemetryUtils.js.map +1 -0
  66. package/package.json +2 -2
  67. package/dist/useBucketArtifacts.d.ts +0 -16
  68. package/dist/useBucketArtifacts.d.ts.map +0 -1
  69. package/dist/useBucketArtifacts.js +0 -19
  70. package/dist/useBucketArtifacts.js.map +0 -1
  71. package/dist/useSubcomponentArtifacts.d.ts +0 -44
  72. package/dist/useSubcomponentArtifacts.d.ts.map +0 -1
  73. package/dist/useSubcomponentArtifacts.js.map +0 -1
package/README.md CHANGED
@@ -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,51 +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.
93
+
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
+ ```
52
141
 
53
- > See [Static assets & runtime stylesheets](#static-assets--runtime-stylesheets)
54
- > below — you must copy the web component's `du-assets/` folder **and its stylesheets**
55
- > into your build output (and serve raw CSS in dev), or PDF rendering,
56
- > translations, and **icons** will silently break with no build error.
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`.
57
147
 
58
148
  ## Props
59
149
 
60
150
  | Prop | Type | Required | Default | Description |
61
151
  | -------------------------------- | ---------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
- | `sdk` | `UiPath` | Yes | — | UiPath SDK instance for authentication and API calls |
63
- | `data` | `ContentValidationData` | Yes | — | Document data containing bucket paths, document ID, and folder references |
64
- | `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` |
65
156
  | `theme` | `'light' \| 'dark' \| 'light-hc' \| 'dark-hc'` | No | `'light'` | Visual theme |
66
157
  | `language` | `ValidationStationLanguage` | No | `English` | UI language (see enum below) |
67
158
  | `isReadonly` | `boolean` | No | `false` | When `true`, renders in read-only mode |
68
- | `options` | `IValidationStationOptions` | No | — | Fine-grained UI feature flags |
69
- | `save={{ validate: false }}` | `{ validate: boolean }` | No | — | Trigger **save as draft**. ⚠ Requires `options.emitDtoStateChanges: true` — otherwise the web component 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** |
70
162
  | `save={{ validate: true }}` | `{ validate: boolean }` | No | — | Trigger **submit** — runs validation first, then saves. |
71
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. |
72
164
  | `setFieldValueByPath` | `SetFieldValueByPath` | No | — | Set a field value addressed by a path of `{ fieldName, valueIndex }` segments |
73
165
  | `selectAndFocusFieldValueByPath` | `SelectAndFocusFieldValueByPath` | No | — | Select and focus a field value addressed by a path; focuses the document reference if any |
74
166
  | `deleteFieldValueByPath` | `DeleteFieldValueByPath` | No | — | Delete a field value addressed by a path |
75
167
 
76
- > 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).
77
169
 
78
170
  ### Reacting to save / draft / exception flows
79
171
 
80
- 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.
81
173
 
82
- | Callback | User action | Signature | What the widget does | What the host does |
83
- | --------------------------- | ----------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
84
- | `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.). |
85
- | `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. |
86
- | `onReportExceptionComplete` | **Report as exception** | `(documentId: string, reason: string) => void` | Extracts `documentId` and `reason` from the web component'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. |
87
179
 
88
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.
89
181
 
182
+ All three fire on every user action, regardless of mode — that is the contract. Only `result` varies.
183
+
90
184
  ```tsx
91
185
  import {
92
186
  ValidationStation,
@@ -95,22 +189,24 @@ import {
95
189
  import { OrchestratorDuModule } from "@uipath/uipath-typescript/orchestrator-du-module";
96
190
 
97
191
  function App({ sdk, data, task }) {
98
- const handleSubmitComplete = async (result: SaveValidatedDataResult) => {
99
- if (!result.success) {
100
- 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);
101
196
  return;
102
197
  }
103
198
  await task.complete({ action: "Completed", type: "DocumentValidation" });
104
199
  };
105
200
 
106
- const handleDraftComplete = (result: SaveValidatedDataResult) => {
107
- 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);
108
203
  };
109
204
 
110
- const handleReportException = async (documentId: string, reason: string) => {
205
+ const handleReportException = async (request) => {
206
+ const reason = request.exceptionReport?.Reason ?? "";
111
207
  const response = await new OrchestratorDuModule(sdk).submitExceptionReport(
112
208
  task.id,
113
- documentId,
209
+ request.documentId,
114
210
  reason || "Reported via Validation Station",
115
211
  { folderId: task.folderId },
116
212
  );
@@ -123,16 +219,47 @@ function App({ sdk, data, task }) {
123
219
  <ValidationStation
124
220
  sdk={sdk}
125
221
  data={data}
126
- folderId={task.folderId}
127
- onSubmitComplete={handleSubmitComplete}
128
- onSaveAsDraftComplete={handleDraftComplete}
129
- onReportExceptionComplete={handleReportException}
222
+ onSubmit={handleSubmit}
223
+ onSaveAsDraft={handleSaveAsDraft}
224
+ onReportException={handleReportException}
130
225
  />
131
226
  );
132
227
  }
133
228
  ```
134
229
 
135
- > 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).
136
263
 
137
264
  ## Language enum
138
265
 
@@ -162,23 +289,50 @@ ValidationStationLanguage.ChineseTraditional; // "zh-TW"
162
289
  All parameter types are re-exported from the package for convenience:
163
290
 
164
291
  ```ts
165
- 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";
166
299
  import type {
167
300
  ValidationStationProps,
301
+ ValidationStationWcConfig,
302
+ DuArtifactsSource,
303
+ DuDocumentArtifacts,
168
304
  IValidationStationOptions,
305
+ IVsSaveValidatedDataRequest,
306
+ IVsSaveValidatedDataAsDraftRequest,
307
+ IVsSaveExceptionReportRequest,
169
308
  SaveValidatedDataResult,
170
309
  SetFieldValueByPath,
171
310
  SelectAndFocusFieldValueByPath,
172
311
  DeleteFieldValueByPath,
312
+ ValidationStationEventProps,
313
+ VsStateEventProps,
314
+ VsSaveResultEventProps,
315
+ IFieldValueDetailsDto,
316
+ EvaluatedBusinessRulesForFieldValueDto,
317
+ ISaveResult,
318
+ SetFieldValueByPathResult,
319
+ SelectAndFocusFieldValueByPathResult,
320
+ DeleteFieldValueByPathResult,
173
321
  } from "@uipath/ui-widgets-validation-station";
174
322
  ```
175
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
+
176
328
  ## Examples
177
329
 
178
330
  ### Setting a field value by path
179
331
 
180
332
  Address fields by path when you have nested groups or table rows. Each segment is `{ fieldName, valueIndex }`.
181
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
+
182
336
  ```tsx
183
337
  import { useState } from "react";
184
338
  import {
@@ -209,7 +363,6 @@ function App({ sdk, data }) {
209
363
  <ValidationStation
210
364
  sdk={sdk}
211
365
  data={data}
212
- folderId={67}
213
366
  setFieldValueByPath={fieldValueByPath}
214
367
  />
215
368
  </>
@@ -248,7 +401,6 @@ function App({ sdk, data }) {
248
401
  <ValidationStation
249
402
  sdk={sdk}
250
403
  data={data}
251
- folderId={67}
252
404
  selectAndFocusFieldValueByPath={focus}
253
405
  />
254
406
  </>
@@ -262,182 +414,223 @@ function App({ sdk, data }) {
262
414
  const [save, setSave] = useState<{ validate: boolean } | undefined>(undefined);
263
415
 
264
416
  <button onClick={() => setSave({ validate: true })}>Save</button>
265
- <ValidationStation sdk={sdk} data={data} folderId={1} save={save} />
417
+ <ValidationStation sdk={sdk} data={data} save={save} />
266
418
  ```
267
419
 
268
- ## Static assets & runtime stylesheets
420
+ ## Hosting the web component
269
421
 
270
- The underlying web component resolves several files **at runtime**, relative
271
- to where its 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/`** — PDF.js worker, cmaps, wasm, and i18n translations.
274
- - **`styles.css`** — fetched as raw CSS text and adopted into the component's
275
- **shadow root**. This is what styles the icons (`<mat-icon>`) and everything
276
- else _inside_ the shadow boundary.
277
- - **`fonts.css`** + **`media/`** — the Apollo / Material Icons `@font-face`
278
- declarations and the font files they reference.
428
+ That means there is no bundler configuration to write. You need two things:
279
429
 
280
- > **The React wrapper already imports `styles.css` and `fonts.css` as ES
281
- > modules for you**, so the _light DOM_ concerns (`@font-face` registration,
282
- > plus CDK overlays like menus/tooltips that portal to `document.body`) are
283
- > handled automatically — you do **not** add those imports yourself. What you
284
- > still have to handle is making the same files reachable by the web component's
285
- > **runtime `fetch`**, covered below.
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.
286
434
 
287
- **These files must be deployed at the same path level as your output bundle.**
288
- If they're missing there's no build error — they silently 404 at runtime:
289
- PDFs fail to render, and because the shadow root never receives `styles.css`,
290
- **icons fall back to a system font and render as empty boxes or raw text**.
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
+ ```
291
446
 
292
- There are two things to get right:
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:
293
453
 
294
- 1. **Build** — copy `du-assets/`, `styles.css`, `fonts.css`, and `media/` next
295
- to your emitted JS chunks.
296
- 2. **Dev server** — if your dev server rewrites `.css` requests into JS modules
297
- (Vite does this), the web component's `fetch("styles.css")` receives JavaScript instead
298
- of CSS, `CSSStyleSheet.replaceSync()` parses nothing, and the shadow-root
299
- styles never load (→ broken icons). You must serve the **raw CSS** for that
300
- fetch. Bundlers that serve copied files verbatim in dev (e.g.
301
- webpack-dev-server) don't have this problem — copying alone is enough.
454
+ ```ts
455
+ import {
456
+ configureValidationStationWc,
457
+ joinDeploymentUrl,
458
+ } from "@uipath/ui-widgets-validation-station";
302
459
 
303
- ### Vite
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,
467
+ });
468
+ ```
304
469
 
305
- Two plugins: one copies the runtime files after a build, one serves raw CSS to
306
- the web component's `fetch` during dev. `optimizeDeps.exclude` is also required — Vite's
307
- pre-bundler rewrites `import.meta.url`, which breaks the web component's runtime
308
- resolution.
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).
309
474
 
310
- ```ts
311
- // vite.config.ts
312
- import react from "@vitejs/plugin-react";
313
- import { cp, readFile } from "node:fs/promises";
314
- import { createRequire } from "node:module";
315
- import { dirname, resolve } from "node:path";
316
- import { defineConfig, type Plugin } from "vite";
317
-
318
- const require = createRequire(import.meta.url);
319
-
320
- const WC_ROOT = dirname(
321
- require.resolve("@uipath/du-validation-station-wc/package.json"),
322
- );
323
-
324
- // Stylesheets the web component fetches (as raw CSS) at runtime to adopt into its
325
- // shadow root.
326
- const WC_RUNTIME_CSS = ["styles.css", "fonts.css"];
327
-
328
- // BUILD: place the web component's runtime files next to the emitted JS chunks, where
329
- // `import.meta.url` will resolve them.
330
- function copyDuValidationStationAssets(): Plugin {
331
- let assetsDir = "";
332
- return {
333
- name: "copy-du-validation-station-assets",
334
- apply: "build",
335
- configResolved(config) {
336
- assetsDir = resolve(
337
- config.root,
338
- config.build.outDir,
339
- config.build.assetsDir,
340
- );
341
- },
342
- async closeBundle() {
343
- await cp(resolve(WC_ROOT, "du-assets"), resolve(assetsDir, "du-assets"), {
344
- recursive: true,
345
- });
346
- await cp(resolve(WC_ROOT, "media"), resolve(assetsDir, "media"), {
347
- recursive: true,
348
- });
349
- for (const css of WC_RUNTIME_CSS) {
350
- await cp(resolve(WC_ROOT, css), resolve(assetsDir, css));
351
- }
352
- },
353
- };
354
- }
475
+ The served directory must keep the package's own layout, because the bundle
476
+ resolves these against its own `import.meta.url`:
355
477
 
356
- // DEV: Vite serves any `.css` request as a JS module. Return the real CSS to
357
- // the web component's raw `fetch` (identified by `Sec-Fetch-Dest: empty`), while letting
358
- // genuine ES-module imports (`Sec-Fetch-Dest: script`) pass through to Vite.
359
- function serveDuValidationStationRawCss(): Plugin {
360
- const pattern = new RegExp(
361
- `/@uipath/du-validation-station-wc/(${WC_RUNTIME_CSS.join("|")})$`,
362
- );
363
- return {
364
- name: "serve-du-validation-station-raw-css",
365
- apply: "serve",
366
- configureServer(server) {
367
- server.middlewares.use((req, res, next) => {
368
- if (req.headers["sec-fetch-dest"] !== "empty") return next();
369
- const match = pattern.exec((req.url ?? "").split("?")[0]);
370
- if (!match) return next();
371
- readFile(resolve(WC_ROOT, match[1]), "utf8").then((css) => {
372
- res.setHeader("Content-Type", "text/css");
373
- res.end(css);
374
- }, next);
375
- });
376
- },
377
- };
378
- }
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
+ ```
379
488
 
380
- export default defineConfig({
381
- plugins: [
382
- react(),
383
- copyDuValidationStationAssets(),
384
- serveDuValidationStationRawCss(),
385
- ],
386
- optimizeDeps: {
387
- exclude: ["@uipath/du-validation-station-wc"],
388
- },
389
- });
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();
390
540
  ```
391
541
 
392
- ### webpack
393
-
394
- Use [`copy-webpack-plugin`](https://github.com/webpack-contrib/copy-webpack-plugin) to copy `du-assets/`, the stylesheets, and `media/` next to your bundle, **and** opt the web component bundle out of webpack's `new URL(..., import.meta.url)` parsing — the web component uses that pattern for its runtime resolution, and webpack will otherwise try to bundle the directory and fail with `Module not found: Error: Can't resolve './du-assets/'`. webpack-dev-server serves the copied files verbatim, so no separate raw-CSS handling is needed.
395
-
396
- ```js
397
- // webpack.config.js
398
- const CopyPlugin = require("copy-webpack-plugin");
399
- const path = require("path");
400
-
401
- const wcRoot = path.dirname(
402
- require.resolve("@uipath/du-validation-station-wc/package.json"),
403
- );
404
-
405
- module.exports = {
406
- module: {
407
- rules: [
408
- // Don't parse runtime URL / dynamic-require expressions inside the web component —
409
- // its assets and stylesheets are resolved at runtime from `import.meta.url`.
410
- {
411
- test: /node_modules[\\/]@uipath[\\/]du-validation-station-wc[\\/].*\.js$/,
412
- parser: {
413
- url: false,
414
- exprContextCritical: false,
415
- unknownContextCritical: false,
416
- },
417
- },
418
- ],
419
- },
420
- plugins: [
421
- new CopyPlugin({
422
- patterns: [
423
- { from: `${wcRoot}/du-assets`, to: "assets/du-assets" },
424
- { from: `${wcRoot}/media`, to: "assets/media" },
425
- { from: `${wcRoot}/styles.css`, to: "assets/styles.css" },
426
- { from: `${wcRoot}/fonts.css`, to: "assets/fonts.css" },
427
- ],
428
- }),
429
- ],
430
- };
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) => …}
431
570
  ```
432
571
 
433
- ### 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
434
628
 
435
- Any asset-copy mechanism works — Angular's `assets` array,
436
- `rollup-plugin-copy`, a `postbuild` npm script with `cp -r`, etc. The
437
- requirement is the same: the final deployed layout must have `du-assets/`,
438
- `styles.css`, `fonts.css`, and `media/` sitting next to the JS chunks that
439
- import the web component. If your dev server transforms `.css` into JS modules, also make
440
- sure the web component's runtime `fetch` for `styles.css`/`fonts.css` receives raw CSS.
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.
441
634
 
442
635
  ## Development
443
636