@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.
- package/README.md +388 -127
- package/dist/ValidationStation.d.ts +12 -0
- package/dist/ValidationStation.d.ts.map +1 -1
- package/dist/ValidationStation.js +72 -49
- package/dist/ValidationStation.js.map +1 -1
- package/dist/ValidationStation.stories.d.ts.map +1 -1
- package/dist/ValidationStation.stories.js +30 -19
- package/dist/ValidationStation.stories.js.map +1 -1
- package/dist/bindWcEvents.d.ts +25 -0
- package/dist/bindWcEvents.d.ts.map +1 -0
- package/dist/bindWcEvents.js +59 -0
- package/dist/bindWcEvents.js.map +1 -0
- package/dist/bucketArtifactsUtil.d.ts +13 -3
- package/dist/bucketArtifactsUtil.d.ts.map +1 -1
- package/dist/bucketArtifactsUtil.js +50 -33
- package/dist/bucketArtifactsUtil.js.map +1 -1
- package/dist/index.d.ts +14 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +13 -0
- package/dist/index.js.map +1 -1
- package/dist/loadValidationStationWc.d.ts +73 -4
- package/dist/loadValidationStationWc.d.ts.map +1 -1
- package/dist/loadValidationStationWc.js +104 -9
- package/dist/loadValidationStationWc.js.map +1 -1
- package/dist/saveHandlers.d.ts +19 -0
- package/dist/saveHandlers.d.ts.map +1 -0
- package/dist/saveHandlers.js +41 -0
- package/dist/saveHandlers.js.map +1 -0
- package/dist/saveValidatedDataUtil.d.ts +2 -2
- package/dist/saveValidatedDataUtil.d.ts.map +1 -1
- package/dist/saveValidatedDataUtil.js +32 -22
- package/dist/saveValidatedDataUtil.js.map +1 -1
- package/dist/subcomponents/CompactBusinessRules.d.ts +8 -0
- package/dist/subcomponents/CompactBusinessRules.d.ts.map +1 -0
- package/dist/subcomponents/CompactBusinessRules.js +55 -0
- package/dist/subcomponents/CompactBusinessRules.js.map +1 -0
- package/dist/subcomponents/CompactDocTypeField.d.ts +8 -0
- package/dist/subcomponents/CompactDocTypeField.d.ts.map +1 -0
- package/dist/subcomponents/CompactDocTypeField.js +42 -0
- package/dist/subcomponents/CompactDocTypeField.js.map +1 -0
- package/dist/subcomponents/CompactFieldsForm.d.ts +10 -0
- package/dist/subcomponents/CompactFieldsForm.d.ts.map +1 -0
- package/dist/subcomponents/CompactFieldsForm.js +68 -0
- package/dist/subcomponents/CompactFieldsForm.js.map +1 -0
- package/dist/subcomponents/CompactTableEditor.d.ts +11 -0
- package/dist/subcomponents/CompactTableEditor.d.ts.map +1 -0
- package/dist/subcomponents/CompactTableEditor.js +61 -0
- package/dist/subcomponents/CompactTableEditor.js.map +1 -0
- package/dist/subcomponents/DocumentViewer.d.ts +8 -0
- package/dist/subcomponents/DocumentViewer.d.ts.map +1 -0
- package/dist/subcomponents/DocumentViewer.js +52 -0
- package/dist/subcomponents/DocumentViewer.js.map +1 -0
- package/dist/subcomponents/shared.d.ts +35 -0
- package/dist/subcomponents/shared.d.ts.map +1 -0
- package/dist/subcomponents/shared.js +36 -0
- package/dist/subcomponents/shared.js.map +1 -0
- package/dist/subcomponents/types.d.ts +82 -0
- package/dist/subcomponents/types.d.ts.map +1 -0
- package/dist/subcomponents/types.js +2 -0
- package/dist/subcomponents/types.js.map +1 -0
- package/dist/subcomponents/useWcElement.d.ts +43 -0
- package/dist/subcomponents/useWcElement.d.ts.map +1 -0
- package/dist/subcomponents/useWcElement.js +38 -0
- package/dist/subcomponents/useWcElement.js.map +1 -0
- package/dist/types.d.ts +153 -34
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +15 -0
- package/dist/types.js.map +1 -1
- package/dist/urlUtil.d.ts +9 -0
- package/dist/urlUtil.d.ts.map +1 -0
- package/dist/urlUtil.js +11 -0
- package/dist/urlUtil.js.map +1 -0
- package/dist/useDuDocumentArtifacts.d.ts +12 -0
- package/dist/useDuDocumentArtifacts.d.ts.map +1 -0
- package/dist/useDuDocumentArtifacts.js +11 -0
- package/dist/useDuDocumentArtifacts.js.map +1 -0
- package/dist/useResolvedArtifacts.d.ts +41 -0
- package/dist/useResolvedArtifacts.d.ts.map +1 -0
- package/dist/useResolvedArtifacts.js +85 -0
- package/dist/useResolvedArtifacts.js.map +1 -0
- package/dist/useWcReady.d.ts +12 -0
- package/dist/useWcReady.d.ts.map +1 -0
- package/dist/useWcReady.js +31 -0
- package/dist/useWcReady.js.map +1 -0
- package/dist/utils/telemetryUtils.d.ts +3 -0
- package/dist/utils/telemetryUtils.d.ts.map +1 -0
- package/dist/utils/telemetryUtils.js +10 -0
- package/dist/utils/telemetryUtils.js.map +1 -0
- package/package.json +6 -5
- package/dist/useBucketArtifacts.d.ts +0 -8
- package/dist/useBucketArtifacts.d.ts.map +0 -1
- package/dist/useBucketArtifacts.js +0 -39
- 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.
|
|
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
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
>
|
|
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` |
|
|
62
|
-
| `data` | `ContentValidationData` |
|
|
63
|
-
| `
|
|
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
|
-
| `
|
|
68
|
-
| `
|
|
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
|
-
>
|
|
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
|
|
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
|
|
82
|
-
|
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
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
|
-
|
|
98
|
-
|
|
99
|
-
|
|
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
|
|
106
|
-
if (!result
|
|
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 (
|
|
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
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
onReportExceptionComplete={handleReportException}
|
|
222
|
+
onSubmit={handleSubmit}
|
|
223
|
+
onSaveAsDraft={handleSaveAsDraft}
|
|
224
|
+
onReportException={handleReportException}
|
|
129
225
|
/>
|
|
130
226
|
);
|
|
131
227
|
}
|
|
132
228
|
```
|
|
133
229
|
|
|
134
|
-
>
|
|
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 {
|
|
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}
|
|
417
|
+
<ValidationStation sdk={sdk} data={data} save={save} />
|
|
265
418
|
```
|
|
266
419
|
|
|
267
|
-
##
|
|
420
|
+
## Hosting the web component
|
|
268
421
|
|
|
269
|
-
The
|
|
270
|
-
|
|
271
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
282
|
-
|
|
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
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
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
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
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
|
-
`
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
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
|
-
|
|
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
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
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
|
|