@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.
- package/README.md +384 -191
- 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/bucketArtifactsUtil.d.ts +13 -3
- package/dist/bucketArtifactsUtil.d.ts.map +1 -1
- package/dist/bucketArtifactsUtil.js +42 -32
- package/dist/bucketArtifactsUtil.js.map +1 -1
- package/dist/index.d.ts +9 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -1
- package/dist/index.js.map +1 -1
- package/dist/loadValidationStationWc.d.ts +59 -7
- package/dist/loadValidationStationWc.d.ts.map +1 -1
- package/dist/loadValidationStationWc.js +81 -20
- 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/CompactFieldsForm.d.ts +4 -4
- package/dist/subcomponents/CompactFieldsForm.d.ts.map +1 -1
- package/dist/subcomponents/CompactFieldsForm.js +8 -27
- package/dist/subcomponents/CompactFieldsForm.js.map +1 -1
- package/dist/subcomponents/shared.d.ts +3 -3
- package/dist/subcomponents/shared.d.ts.map +1 -1
- package/dist/subcomponents/shared.js.map +1 -1
- package/dist/subcomponents/types.d.ts +8 -54
- package/dist/subcomponents/types.d.ts.map +1 -1
- package/dist/subcomponents/useWcElement.d.ts +5 -6
- package/dist/subcomponents/useWcElement.d.ts.map +1 -1
- package/dist/subcomponents/useWcElement.js +2 -4
- package/dist/subcomponents/useWcElement.js.map +1 -1
- package/dist/types.d.ts +150 -31
- 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/{useSubcomponentArtifacts.js → useResolvedArtifacts.js} +24 -26
- package/dist/useResolvedArtifacts.js.map +1 -0
- package/dist/useWcReady.d.ts +7 -3
- package/dist/useWcReady.d.ts.map +1 -1
- package/dist/useWcReady.js +11 -3
- package/dist/useWcReady.js.map +1 -1
- 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 +2 -2
- package/dist/useBucketArtifacts.d.ts +0 -16
- package/dist/useBucketArtifacts.d.ts.map +0 -1
- package/dist/useBucketArtifacts.js +0 -19
- package/dist/useBucketArtifacts.js.map +0 -1
- package/dist/useSubcomponentArtifacts.d.ts +0 -44
- package/dist/useSubcomponentArtifacts.d.ts.map +0 -1
- 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
|
|
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
|
-
>
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
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` |
|
|
63
|
-
| `data` | `ContentValidationData` |
|
|
64
|
-
| `
|
|
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
|
-
| `
|
|
69
|
-
| `
|
|
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
|
-
>
|
|
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
|
|
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
|
|
83
|
-
|
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
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
|
-
|
|
99
|
-
|
|
100
|
-
|
|
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
|
|
107
|
-
if (!result
|
|
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 (
|
|
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
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
onReportExceptionComplete={handleReportException}
|
|
222
|
+
onSubmit={handleSubmit}
|
|
223
|
+
onSaveAsDraft={handleSaveAsDraft}
|
|
224
|
+
onReportException={handleReportException}
|
|
130
225
|
/>
|
|
131
226
|
);
|
|
132
227
|
}
|
|
133
228
|
```
|
|
134
229
|
|
|
135
|
-
>
|
|
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 {
|
|
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}
|
|
417
|
+
<ValidationStation sdk={sdk} data={data} save={save} />
|
|
266
418
|
```
|
|
267
419
|
|
|
268
|
-
##
|
|
420
|
+
## Hosting the web component
|
|
269
421
|
|
|
270
|
-
The
|
|
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
|
-
- **`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
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
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
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
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
|
-
|
|
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
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
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
|
-
|
|
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
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
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
|
-
|
|
311
|
-
|
|
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
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
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
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
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
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
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
|
-
|
|
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
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
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
|
|