@rippling/pebble-sdui-web 0.14.0 → 0.15.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/package.json +1 -6
- package/dist/catalogs/core/action-params.d.ts +0 -96
- package/dist/catalogs/core/actions.d.ts +0 -21
- package/dist/catalogs/core/catalog.d.ts +0 -33
- package/dist/catalogs/core/component-events.d.ts +0 -193
- package/dist/catalogs/core/component-props.d.ts +0 -5312
- package/dist/catalogs/core/components.d.ts +0 -194
- package/dist/catalogs/core/function-params.d.ts +0 -5
- package/dist/catalogs/core/functions.d.ts +0 -5
- package/dist/catalogs/core/index.cjs +0 -137
- package/dist/catalogs/core/index.cjs.map +0 -1
- package/dist/catalogs/core/index.d.ts +0 -13
- package/dist/catalogs/core/index.js +0 -31848
- package/dist/catalogs/core/index.js.map +0 -1
- package/dist/catalogs/core/render.d.ts +0 -20
- package/dist/docs/typescript/web/catalogs/core/actions.md +0 -645
- package/dist/docs/typescript/web/catalogs/core/components.md +0 -6580
- package/dist/docs/typescript/web/catalogs/core/computed-functions.md +0 -6
- package/dist/docs/typescript/web/catalogs/core/definitions.md +0 -4431
- package/dist/docs/typescript/web/catalogs/core/readme.md +0 -16
- package/dist/docs/typescript/web/catalogs/core/types.md +0 -4833
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
import { ElementNode } from '../../core/elements';
|
|
2
|
-
import { CoreSpec } from '../../core/spec';
|
|
3
|
-
export interface CatalogSpec extends CoreSpec {
|
|
4
|
-
platform: 'web';
|
|
5
|
-
catalog: string;
|
|
6
|
-
catalogVersion: string;
|
|
7
|
-
}
|
|
8
|
-
type CatalogElementNode = ElementNode<'web', 'core'>;
|
|
9
|
-
/**
|
|
10
|
-
* Render an element tree into a flat json-render spec tagged with
|
|
11
|
-
* the core catalog name and version.
|
|
12
|
-
*
|
|
13
|
-
* This is the catalog-level render — consumers import this instead
|
|
14
|
-
* of using createSpec().render() directly.
|
|
15
|
-
*/
|
|
16
|
-
export declare function render<TState extends object = Record<string, unknown>>(opts: {
|
|
17
|
-
root: CatalogElementNode;
|
|
18
|
-
state?: TState;
|
|
19
|
-
}): CatalogSpec;
|
|
20
|
-
export {};
|
|
@@ -1,645 +0,0 @@
|
|
|
1
|
-
<!-- Auto-generated from catalogs/core.catalog.json; do not edit directly. -->
|
|
2
|
-
# core Actions
|
|
3
|
-
|
|
4
|
-
Import action creators from `@rippling/pebble-sdui-web/catalogs/core`. Read [definitions.md](./definitions.md) for enum values linked from param tables.
|
|
5
|
-
|
|
6
|
-
## applyMutexRules
|
|
7
|
-
|
|
8
|
-
Normalize an array selection against mutual-exclusion rules. Diffs the array at `valuePath` against the mirror at `previousValuePath` to learn what was just added, applies the rules at `rulesPath`, writes the normalized array back to `valuePath`, and copies it to `previousValuePath`. Use as the `on.change` action of a multi-select input bound to `valuePath`.
|
|
9
|
-
|
|
10
|
-
valuePath: JSON Pointer to the bound array state of a multi-select input (e.g. `value: { $bindState: "/companySettings" }`).
|
|
11
|
-
previousValuePath: JSON Pointer to a sibling array used as the diff mirror. Seed initial state with the same value as `valuePath`; the action keeps it in sync on every run.
|
|
12
|
-
rulesPath: JSON Pointer to the rules array. Shape: `Array<{ group: string[], exclusive: "all" | "group" }>`. Rules apply in order.
|
|
13
|
-
`exclusive: "all"` — group members are mutex with EVERYTHING. Clicking a member evicts every other selection; clicking anything else evicts every member of the group.
|
|
14
|
-
`exclusive: "group"` — pairwise mutex WITHIN the group. Clicking a member evicts other members of the same group; selections outside the group are untouched.
|
|
15
|
-
The input must be controlled via `value: { $bindState: valuePath }` for the normalization to render. Uncontrolled (defaultValue-only) inputs will not reflect the action's writes.
|
|
16
|
-
Non-string entries in `value` and unknown `exclusive` modes are ignored. If `value` or `rules` are missing/non-array, the action no-ops.
|
|
17
|
-
|
|
18
|
-
Catalog key: `applyMutexRules`
|
|
19
|
-
Creator: `applyMutexRules`
|
|
20
|
-
Params type: `ApplyMutexRulesParams`
|
|
21
|
-
|
|
22
|
-
### Params
|
|
23
|
-
|
|
24
|
-
| Name | Required | Type | Description |
|
|
25
|
-
|---|---:|---|---|
|
|
26
|
-
| `previousValuePath` | yes | string | |
|
|
27
|
-
| `rulesPath` | yes | string | |
|
|
28
|
-
| `valuePath` | yes | string | |
|
|
29
|
-
|
|
30
|
-
No additional properties.
|
|
31
|
-
|
|
32
|
-
### Usage Shape
|
|
33
|
-
|
|
34
|
-
```ts
|
|
35
|
-
on: {
|
|
36
|
-
press: applyMutexRules({ ... })
|
|
37
|
-
}
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## debouncedAction
|
|
41
|
-
|
|
42
|
-
Generic debouncing wrapper for any core action handler. Delays execution until user stops triggering for the specified duration.
|
|
43
|
-
|
|
44
|
-
Catalog key: `debouncedAction`
|
|
45
|
-
Creator: `debouncedAction`
|
|
46
|
-
Params type: `DebouncedActionParams`
|
|
47
|
-
|
|
48
|
-
### Params
|
|
49
|
-
|
|
50
|
-
| Name | Required | Type | Description |
|
|
51
|
-
|---|---:|---|---|
|
|
52
|
-
| `action` | yes | string | |
|
|
53
|
-
| `debounceKey` | no | string | |
|
|
54
|
-
| `debounceMs` | yes | number | |
|
|
55
|
-
| `params` | no | [DebouncedActionParamsParam](./types.md#debouncedactionparamsparam) | |
|
|
56
|
-
|
|
57
|
-
No additional properties.
|
|
58
|
-
|
|
59
|
-
### Usage Shape
|
|
60
|
-
|
|
61
|
-
```ts
|
|
62
|
-
on: {
|
|
63
|
-
press: debouncedAction({ ... })
|
|
64
|
-
}
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
## fetchQuery
|
|
68
|
-
|
|
69
|
-
Fetch data via React Query and mirror result/status/error into SDUI state.
|
|
70
|
-
|
|
71
|
-
Use when a spec needs cached server data to become readable through `$state`, including loading/error UI and later cache-driven refreshes.
|
|
72
|
-
|
|
73
|
-
Prefer `prefetchQuery` when you only want to warm the cache and do not need immediate SDUI state writes.
|
|
74
|
-
Prefer `triggerApi` for one-off imperative calls that do not need React Query caching, deduping, invalidation, or retry behavior.
|
|
75
|
-
|
|
76
|
-
Parameter details are defined on the action schema properties and are intended to be surfaced by catalog/tooling output.
|
|
77
|
-
|
|
78
|
-
Subsequent actions:
|
|
79
|
-
- Configure multiple follow-up actions by passing an array to `onSuccess` or `onError`
|
|
80
|
-
- Lifecycle actions run sequentially after the parent state write
|
|
81
|
-
- Each chained action receives the latest state produced by the parent action and any earlier chained actions
|
|
82
|
-
|
|
83
|
-
Example:
|
|
84
|
-
```json
|
|
85
|
-
{
|
|
86
|
-
"action": "fetchQuery",
|
|
87
|
-
"params": {
|
|
88
|
-
"queryKey": { "namespace": "hr", "key": "employees", "params": { "companyId": "c_123" } },
|
|
89
|
-
"request": {
|
|
90
|
-
"url": "/api/hr/employees",
|
|
91
|
-
"method": "GET",
|
|
92
|
-
"queryParams": { "companyId": "c_123" }
|
|
93
|
-
},
|
|
94
|
-
"stateTarget": { "path": "/employees" },
|
|
95
|
-
"onSuccess": [
|
|
96
|
-
{
|
|
97
|
-
"action": "showNotification",
|
|
98
|
-
"params": { "variant": "success", "message": "Employees loaded" }
|
|
99
|
-
},
|
|
100
|
-
{
|
|
101
|
-
"action": "setState",
|
|
102
|
-
"params": { "statePath": "/employees/loadedFromAction", "value": true }
|
|
103
|
-
}
|
|
104
|
-
]
|
|
105
|
-
}
|
|
106
|
-
}
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
Catalog key: `fetchQuery`
|
|
110
|
-
Creator: `fetchQuery`
|
|
111
|
-
Params type: `FetchQueryParams`
|
|
112
|
-
|
|
113
|
-
### Params
|
|
114
|
-
|
|
115
|
-
| Name | Required | Type | Description |
|
|
116
|
-
|---|---:|---|---|
|
|
117
|
-
| `onError` | no | Record<string, unknown>[] | Actions to run sequentially after an error state write. |
|
|
118
|
-
| `onSuccess` | no | Record<string, unknown>[] | Actions to run sequentially after a successful state write. |
|
|
119
|
-
| `queryKey` | yes | Record<string, unknown> | Stable React Query cache key for this fetch. |
|
|
120
|
-
| `queryOptions` | no | Record<string, unknown> | Optional React Query fetch behavior. |
|
|
121
|
-
| `request` | yes | Record<string, unknown> | Serializable request descriptor executed for the query. |
|
|
122
|
-
| `stateTarget` | yes | Record<string, unknown> | State path where query data, status, and error are mirrored. |
|
|
123
|
-
|
|
124
|
-
No additional properties.
|
|
125
|
-
|
|
126
|
-
### Usage Shape
|
|
127
|
-
|
|
128
|
-
```ts
|
|
129
|
-
on: {
|
|
130
|
-
press: fetchQuery({ ... })
|
|
131
|
-
}
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
## historyPushState
|
|
135
|
-
|
|
136
|
-
Update URL query parameters using browser History API without triggering React Router re-renders.
|
|
137
|
-
|
|
138
|
-
Catalog key: `historyPushState`
|
|
139
|
-
Creator: `historyPushState`
|
|
140
|
-
Params type: `HistoryPushStateParams`
|
|
141
|
-
|
|
142
|
-
### Params
|
|
143
|
-
|
|
144
|
-
_No fields._
|
|
145
|
-
|
|
146
|
-
Additional properties: string.
|
|
147
|
-
|
|
148
|
-
### Usage Shape
|
|
149
|
-
|
|
150
|
-
```ts
|
|
151
|
-
on: {
|
|
152
|
-
press: historyPushState({ ... })
|
|
153
|
-
}
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
## invalidateQuery
|
|
157
|
-
|
|
158
|
-
Invalidate one or more React Query keys.
|
|
159
|
-
|
|
160
|
-
Use when some other action changed server state and existing cached reads should be marked stale and optionally refetched.
|
|
161
|
-
|
|
162
|
-
Prefer `runMutation` when the same SDUI action should both perform the write and invalidate related queries as one flow.
|
|
163
|
-
Prefer `fetchQuery` when you need the current action to read data immediately instead of only marking cache entries stale.
|
|
164
|
-
|
|
165
|
-
Parameter details are defined on the action schema properties and are intended to be surfaced by catalog/tooling output.
|
|
166
|
-
|
|
167
|
-
Subsequent actions:
|
|
168
|
-
- Configure multiple follow-up actions by passing an array to `onSuccess` or `onError`
|
|
169
|
-
- Lifecycle actions run sequentially after invalidation completes or fails
|
|
170
|
-
- Each chained action receives the latest state produced by any earlier chained actions
|
|
171
|
-
|
|
172
|
-
Example:
|
|
173
|
-
```json
|
|
174
|
-
{
|
|
175
|
-
"action": "invalidateQuery",
|
|
176
|
-
"params": {
|
|
177
|
-
"targets": [
|
|
178
|
-
{ "namespace": "hr", "key": "employees" }
|
|
179
|
-
],
|
|
180
|
-
"refetchType": "active",
|
|
181
|
-
"onSuccess": [
|
|
182
|
-
{
|
|
183
|
-
"action": "showNotification",
|
|
184
|
-
"params": { "variant": "info", "message": "Employee list refreshing" }
|
|
185
|
-
}
|
|
186
|
-
]
|
|
187
|
-
}
|
|
188
|
-
}
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
Catalog key: `invalidateQuery`
|
|
192
|
-
Creator: `invalidateQuery`
|
|
193
|
-
Params type: `InvalidateQueryParams`
|
|
194
|
-
|
|
195
|
-
### Params
|
|
196
|
-
|
|
197
|
-
| Name | Required | Type | Description |
|
|
198
|
-
|---|---:|---|---|
|
|
199
|
-
| `exact` | no | boolean | When true, invalidates only exact keys instead of prefixes. |
|
|
200
|
-
| `onError` | no | Record<string, unknown>[] | Actions to run sequentially after invalidation fails. |
|
|
201
|
-
| `onSuccess` | no | Record<string, unknown>[] | Actions to run sequentially after invalidation succeeds. |
|
|
202
|
-
| `refetchType` | no | [invalidateQueryRefetchType](./definitions.md#invalidatequeryrefetchtype) | Optional refetch policy used for invalidated queries. |
|
|
203
|
-
| `targets` | yes | Record<string, unknown>[] | One or more query keys or prefixes to invalidate. |
|
|
204
|
-
|
|
205
|
-
No additional properties.
|
|
206
|
-
|
|
207
|
-
### Usage Shape
|
|
208
|
-
|
|
209
|
-
```ts
|
|
210
|
-
on: {
|
|
211
|
-
press: invalidateQuery({ ... })
|
|
212
|
-
}
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
## invalidateSuperGridData
|
|
216
|
-
|
|
217
|
-
Invalidate cached SuperGrid data for a grid and request a backend cache bust.
|
|
218
|
-
|
|
219
|
-
Use after an SDUI mutation changes rows displayed by a SuperGrid.
|
|
220
|
-
Run this after any prerequisite actions, such as triggerApi, in an ordered event action array or runActions chain.
|
|
221
|
-
The action invalidates SuperGrid data and dropdown queries for gridId. Backend cache bust is attempted when the grid supports it.
|
|
222
|
-
|
|
223
|
-
Catalog key: `invalidateSuperGridData`
|
|
224
|
-
Creator: `invalidateSuperGridData`
|
|
225
|
-
Params type: `InvalidateSuperGridDataParams`
|
|
226
|
-
|
|
227
|
-
### Params
|
|
228
|
-
|
|
229
|
-
| Name | Required | Type | Description |
|
|
230
|
-
|---|---:|---|---|
|
|
231
|
-
| `gridId` | yes | string | SuperGrid id whose cached data and dropdown queries should be invalidated. |
|
|
232
|
-
|
|
233
|
-
No additional properties.
|
|
234
|
-
|
|
235
|
-
### Usage Shape
|
|
236
|
-
|
|
237
|
-
```ts
|
|
238
|
-
on: {
|
|
239
|
-
press: invalidateSuperGridData({ ... })
|
|
240
|
-
}
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
## lookupOwnership
|
|
244
|
-
|
|
245
|
-
Look up ownership details for a file path or URL. Detects input type and calls appropriate service.
|
|
246
|
-
|
|
247
|
-
Catalog key: `lookupOwnership`
|
|
248
|
-
Creator: `lookupOwnership`
|
|
249
|
-
Params type: `LookupOwnershipParams`
|
|
250
|
-
|
|
251
|
-
### Params
|
|
252
|
-
|
|
253
|
-
| Name | Required | Type | Description |
|
|
254
|
-
|---|---:|---|---|
|
|
255
|
-
| `input` | yes | string | |
|
|
256
|
-
| `loadingPath` | no | string | |
|
|
257
|
-
| `responsePath` | yes | string | |
|
|
258
|
-
|
|
259
|
-
No additional properties.
|
|
260
|
-
|
|
261
|
-
### Usage Shape
|
|
262
|
-
|
|
263
|
-
```ts
|
|
264
|
-
on: {
|
|
265
|
-
press: lookupOwnership({ ... })
|
|
266
|
-
}
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
## navigate
|
|
270
|
-
|
|
271
|
-
Navigate to a URL path.
|
|
272
|
-
|
|
273
|
-
Page URLs: `/custom-apps/{app_id}/sdui/{page_id}`. Use openInNewTab for external links.
|
|
274
|
-
|
|
275
|
-
Catalog key: `navigate`
|
|
276
|
-
Creator: `navigate`
|
|
277
|
-
Params type: `NavigateParams`
|
|
278
|
-
|
|
279
|
-
### Params
|
|
280
|
-
|
|
281
|
-
| Name | Required | Type | Description |
|
|
282
|
-
|---|---:|---|---|
|
|
283
|
-
| `openInNewTab` | no | boolean | |
|
|
284
|
-
| `path` | yes | string | |
|
|
285
|
-
|
|
286
|
-
No additional properties.
|
|
287
|
-
|
|
288
|
-
### Usage Shape
|
|
289
|
-
|
|
290
|
-
```ts
|
|
291
|
-
on: {
|
|
292
|
-
press: navigate({ ... })
|
|
293
|
-
}
|
|
294
|
-
```
|
|
295
|
-
|
|
296
|
-
## prefetchQuery
|
|
297
|
-
|
|
298
|
-
Warm React Query cache without writing SDUI state.
|
|
299
|
-
|
|
300
|
-
Use when a later route, component, or action is likely to need the data soon, but the current step does not need `$state` updates yet.
|
|
301
|
-
|
|
302
|
-
Prefer `fetchQuery` when the current spec needs loading/data/error state written into SDUI state immediately.
|
|
303
|
-
Prefer doing nothing when preloading would add avoidable network work and there is no clear next consumer.
|
|
304
|
-
|
|
305
|
-
Parameter details are defined on the action schema properties and are intended to be surfaced by catalog/tooling output.
|
|
306
|
-
|
|
307
|
-
This action does not write SDUI state and does not run lifecycle chains in v1.
|
|
308
|
-
|
|
309
|
-
Example:
|
|
310
|
-
```json
|
|
311
|
-
{
|
|
312
|
-
"action": "prefetchQuery",
|
|
313
|
-
"params": {
|
|
314
|
-
"queryKey": { "namespace": "hr", "key": "employees", "params": { "companyId": "c_123" } },
|
|
315
|
-
"request": {
|
|
316
|
-
"url": "/api/hr/employees",
|
|
317
|
-
"method": "GET",
|
|
318
|
-
"queryParams": { "companyId": "c_123" }
|
|
319
|
-
},
|
|
320
|
-
"queryOptions": { "staleTime": 60000 }
|
|
321
|
-
}
|
|
322
|
-
}
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
Catalog key: `prefetchQuery`
|
|
326
|
-
Creator: `prefetchQuery`
|
|
327
|
-
Params type: `PrefetchQueryParams`
|
|
328
|
-
|
|
329
|
-
### Params
|
|
330
|
-
|
|
331
|
-
| Name | Required | Type | Description |
|
|
332
|
-
|---|---:|---|---|
|
|
333
|
-
| `queryKey` | yes | Record<string, unknown> | Stable React Query cache key to warm. |
|
|
334
|
-
| `queryOptions` | no | Record<string, unknown> | Optional React Query prefetch behavior. |
|
|
335
|
-
| `request` | yes | Record<string, unknown> | Serializable request descriptor executed for the prefetch. |
|
|
336
|
-
|
|
337
|
-
No additional properties.
|
|
338
|
-
|
|
339
|
-
### Usage Shape
|
|
340
|
-
|
|
341
|
-
```ts
|
|
342
|
-
on: {
|
|
343
|
-
press: prefetchQuery({ ... })
|
|
344
|
-
}
|
|
345
|
-
```
|
|
346
|
-
|
|
347
|
-
## pushState
|
|
348
|
-
|
|
349
|
-
Append an item to an array in state. Optionally clear another state path.
|
|
350
|
-
|
|
351
|
-
Catalog key: `pushState`
|
|
352
|
-
Creator: `pushState`
|
|
353
|
-
Params type: `PushStateParams`
|
|
354
|
-
|
|
355
|
-
### Params
|
|
356
|
-
|
|
357
|
-
| Name | Required | Type | Description |
|
|
358
|
-
|---|---:|---|---|
|
|
359
|
-
| `clearStatePath` | no | string | |
|
|
360
|
-
| `statePath` | yes | string | |
|
|
361
|
-
| `value` | yes | unknown | |
|
|
362
|
-
|
|
363
|
-
No additional properties.
|
|
364
|
-
|
|
365
|
-
### Usage Shape
|
|
366
|
-
|
|
367
|
-
```ts
|
|
368
|
-
on: {
|
|
369
|
-
press: pushState({ ... })
|
|
370
|
-
}
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
## removeState
|
|
374
|
-
|
|
375
|
-
Remove an item from an array in state by index.
|
|
376
|
-
|
|
377
|
-
Catalog key: `removeState`
|
|
378
|
-
Creator: `removeState`
|
|
379
|
-
Params type: `RemoveStateParams`
|
|
380
|
-
|
|
381
|
-
### Params
|
|
382
|
-
|
|
383
|
-
| Name | Required | Type | Description |
|
|
384
|
-
|---|---:|---|---|
|
|
385
|
-
| `index` | yes | number | |
|
|
386
|
-
| `statePath` | yes | string | |
|
|
387
|
-
|
|
388
|
-
No additional properties.
|
|
389
|
-
|
|
390
|
-
### Usage Shape
|
|
391
|
-
|
|
392
|
-
```ts
|
|
393
|
-
on: {
|
|
394
|
-
press: removeState({ ... })
|
|
395
|
-
}
|
|
396
|
-
```
|
|
397
|
-
|
|
398
|
-
## runActions
|
|
399
|
-
|
|
400
|
-
Run a list of actions sequentially inside a single handler invocation. Use this when a watch chain has multiple synchronous actions — wrapping them collapses the chain to one entry from the renderer's perspective and prevents mid-chain cancellation.
|
|
401
|
-
|
|
402
|
-
actions: array of `{ action, params? }` entries. `action` must match the name of another registered action; `params` is forwarded verbatim to that action's handler.
|
|
403
|
-
Sub-actions are dispatched in order via `await`. All store writes inside the chain batch into a single React re-render, so derived flags (e.g. setArrayIncludes outputs) stay consistent with the writes that produced them.
|
|
404
|
-
Workaround for @json-render/react watch-effect cancellation: the watch IIFE checks a `cancelled` flag between each top-level action, and the cleanup runs as soon as state mutates. Collapsing N actions into one keeps them all immune.
|
|
405
|
-
Unknown sub-action names are skipped silently. Nested runActions calls are supported but rarely useful — prefer a flat list.
|
|
406
|
-
|
|
407
|
-
Catalog key: `runActions`
|
|
408
|
-
Creator: `runActions`
|
|
409
|
-
Params type: `RunActionsParams`
|
|
410
|
-
|
|
411
|
-
### Params
|
|
412
|
-
|
|
413
|
-
| Name | Required | Type | Description |
|
|
414
|
-
|---|---:|---|---|
|
|
415
|
-
| `actions` | yes | [RunActionsParamsAction](./types.md#runactionsparamsaction)[] | |
|
|
416
|
-
|
|
417
|
-
No additional properties.
|
|
418
|
-
|
|
419
|
-
### Usage Shape
|
|
420
|
-
|
|
421
|
-
```ts
|
|
422
|
-
on: {
|
|
423
|
-
press: runActions({ ... })
|
|
424
|
-
}
|
|
425
|
-
```
|
|
426
|
-
|
|
427
|
-
## runMutation
|
|
428
|
-
|
|
429
|
-
Run a write request via React Query mutation flow and mirror lifecycle into SDUI state.
|
|
430
|
-
|
|
431
|
-
Use for writes that should expose pending/success/error state to the spec and optionally invalidate related queries afterward.
|
|
432
|
-
|
|
433
|
-
Prefer `fetchQuery` for reads that should populate cached data rather than perform a write.
|
|
434
|
-
Prefer `triggerApi` only for simple fire-and-forget calls that do not need mutation lifecycle state or query invalidation.
|
|
435
|
-
|
|
436
|
-
Parameter details are defined on the action schema properties and are intended to be surfaced by catalog/tooling output.
|
|
437
|
-
|
|
438
|
-
Subsequent actions:
|
|
439
|
-
- Configure multiple follow-up actions by passing an array to `onSuccess` or `onError`
|
|
440
|
-
- Lifecycle actions run sequentially after the parent state write
|
|
441
|
-
- Each chained action receives the latest state produced by the parent action and any earlier chained actions
|
|
442
|
-
|
|
443
|
-
Example:
|
|
444
|
-
```json
|
|
445
|
-
{
|
|
446
|
-
"action": "runMutation",
|
|
447
|
-
"params": {
|
|
448
|
-
"request": {
|
|
449
|
-
"url": "/api/hr/employees",
|
|
450
|
-
"method": "POST",
|
|
451
|
-
"body": { "name": "Ada" }
|
|
452
|
-
},
|
|
453
|
-
"stateTarget": { "path": "/saveEmployee" },
|
|
454
|
-
"invalidateOnSuccess": [
|
|
455
|
-
{ "namespace": "hr", "key": "employees" }
|
|
456
|
-
],
|
|
457
|
-
"onSuccess": [
|
|
458
|
-
{
|
|
459
|
-
"action": "showNotification",
|
|
460
|
-
"params": { "variant": "success", "message": "Employee saved" }
|
|
461
|
-
},
|
|
462
|
-
{
|
|
463
|
-
"action": "setState",
|
|
464
|
-
"params": { "statePath": "/saveEmployee/finished", "value": true }
|
|
465
|
-
}
|
|
466
|
-
]
|
|
467
|
-
}
|
|
468
|
-
}
|
|
469
|
-
```
|
|
470
|
-
|
|
471
|
-
Catalog key: `runMutation`
|
|
472
|
-
Creator: `runMutation`
|
|
473
|
-
Params type: `RunMutationParams`
|
|
474
|
-
|
|
475
|
-
### Params
|
|
476
|
-
|
|
477
|
-
| Name | Required | Type | Description |
|
|
478
|
-
|---|---:|---|---|
|
|
479
|
-
| `invalidateOnSuccess` | no | Record<string, unknown>[] | Optional query keys to invalidate after success. |
|
|
480
|
-
| `invalidateRefetchType` | no | [invalidateQueryRefetchType](./definitions.md#invalidatequeryrefetchtype) | Optional refetch policy used for invalidated queries. |
|
|
481
|
-
| `mutationKey` | no | Record<string, unknown> | Optional stable key for identifying this mutation. |
|
|
482
|
-
| `mutationOptions` | no | Record<string, unknown> | Optional React Query mutation behavior. |
|
|
483
|
-
| `onError` | no | Record<string, unknown>[] | Actions to run sequentially after an error state write. |
|
|
484
|
-
| `onSuccess` | no | Record<string, unknown>[] | Actions to run sequentially after a successful state write. |
|
|
485
|
-
| `request` | yes | Record<string, unknown> | Serializable request descriptor executed for the mutation. |
|
|
486
|
-
| `stateTarget` | yes | Record<string, unknown> | State path where mutation data, status, and error are mirrored. |
|
|
487
|
-
|
|
488
|
-
No additional properties.
|
|
489
|
-
|
|
490
|
-
### Usage Shape
|
|
491
|
-
|
|
492
|
-
```ts
|
|
493
|
-
on: {
|
|
494
|
-
press: runMutation({ ... })
|
|
495
|
-
}
|
|
496
|
-
```
|
|
497
|
-
|
|
498
|
-
## setArrayIncludes
|
|
499
|
-
|
|
500
|
-
Write a boolean to `flagPath` = whether the array at `arrayPath` includes `value`. Use with element-level `watch` to derive visibility flags from a multi-select state without baking the membership check into the consumer.
|
|
501
|
-
|
|
502
|
-
arrayPath: JSON Pointer to the source array in state.
|
|
503
|
-
value: literal scalar to look up (string, number, or boolean). Element-wise comparison is strict equality.
|
|
504
|
-
flagPath: JSON Pointer where the resulting boolean is written.
|
|
505
|
-
If `arrayPath` does not resolve to an array, writes `false` (treat as "not included").
|
|
506
|
-
Note: json-render `watch` does not fire on mount — seed the initial value of `flagPath` in the builder when you seed `arrayPath`, then `watch` keeps it in sync on subsequent changes.
|
|
507
|
-
|
|
508
|
-
Catalog key: `setArrayIncludes`
|
|
509
|
-
Creator: `setArrayIncludes`
|
|
510
|
-
Params type: `SetArrayIncludesParams`
|
|
511
|
-
|
|
512
|
-
### Params
|
|
513
|
-
|
|
514
|
-
| Name | Required | Type | Description |
|
|
515
|
-
|---|---:|---|---|
|
|
516
|
-
| `arrayPath` | yes | string | |
|
|
517
|
-
| `flagPath` | yes | string | |
|
|
518
|
-
| `value` | yes | string \| number \| boolean | |
|
|
519
|
-
|
|
520
|
-
No additional properties.
|
|
521
|
-
|
|
522
|
-
### Usage Shape
|
|
523
|
-
|
|
524
|
-
```ts
|
|
525
|
-
on: {
|
|
526
|
-
press: setArrayIncludes({ ... })
|
|
527
|
-
}
|
|
528
|
-
```
|
|
529
|
-
|
|
530
|
-
## setState
|
|
531
|
-
|
|
532
|
-
Update a value in the state model at the given statePath.
|
|
533
|
-
|
|
534
|
-
Catalog key: `setState`
|
|
535
|
-
Creator: `setState`
|
|
536
|
-
Params type: `SetStateParams`
|
|
537
|
-
|
|
538
|
-
### Params
|
|
539
|
-
|
|
540
|
-
| Name | Required | Type | Description |
|
|
541
|
-
|---|---:|---|---|
|
|
542
|
-
| `statePath` | yes | string | |
|
|
543
|
-
| `value` | yes | unknown | |
|
|
544
|
-
|
|
545
|
-
No additional properties.
|
|
546
|
-
|
|
547
|
-
### Usage Shape
|
|
548
|
-
|
|
549
|
-
```ts
|
|
550
|
-
on: {
|
|
551
|
-
press: setState({ ... })
|
|
552
|
-
}
|
|
553
|
-
```
|
|
554
|
-
|
|
555
|
-
## showNotification
|
|
556
|
-
|
|
557
|
-
Show a toast notification. Auto-dismisses after 7 seconds.
|
|
558
|
-
|
|
559
|
-
Catalog key: `showNotification`
|
|
560
|
-
Creator: `showNotification`
|
|
561
|
-
Params type: `ShowNotificationParams`
|
|
562
|
-
|
|
563
|
-
### Params
|
|
564
|
-
|
|
565
|
-
| Name | Required | Type | Description |
|
|
566
|
-
|---|---:|---|---|
|
|
567
|
-
| `message` | yes | string | |
|
|
568
|
-
| `variant` | yes | [showNotificationVariant](./definitions.md#shownotificationvariant) | |
|
|
569
|
-
|
|
570
|
-
No additional properties.
|
|
571
|
-
|
|
572
|
-
### Usage Shape
|
|
573
|
-
|
|
574
|
-
```ts
|
|
575
|
-
on: {
|
|
576
|
-
press: showNotification({ ... })
|
|
577
|
-
}
|
|
578
|
-
```
|
|
579
|
-
|
|
580
|
-
## submitFormData
|
|
581
|
-
|
|
582
|
-
Submit FormData to a Rippling endpoint. Sends files as multipart/form-data.
|
|
583
|
-
|
|
584
|
-
url: base path (e.g. "/super_user/upload_to_s3/").
|
|
585
|
-
filesPath: JSON Pointer to File array from FormFileDrop.
|
|
586
|
-
queryParams (optional): query params (e.g. {bucket: states.bucket.state}).
|
|
587
|
-
responsePath (optional): where to store response.
|
|
588
|
-
elevateAccessLevel (optional): forwards elevated-access metadata for privileged upload endpoints.
|
|
589
|
-
|
|
590
|
-
Catalog key: `submitFormData`
|
|
591
|
-
Creator: `submitFormData`
|
|
592
|
-
Params type: `SubmitFormDataParams`
|
|
593
|
-
|
|
594
|
-
### Params
|
|
595
|
-
|
|
596
|
-
| Name | Required | Type | Description |
|
|
597
|
-
|---|---:|---|---|
|
|
598
|
-
| `elevateAccessLevel` | no | boolean | |
|
|
599
|
-
| `filesPath` | yes | string | |
|
|
600
|
-
| `queryParams` | no | [SubmitFormDataParamsQueryParam](./types.md#submitformdataparamsqueryparam) | |
|
|
601
|
-
| `responsePath` | no | string | |
|
|
602
|
-
| `url` | yes | string | |
|
|
603
|
-
|
|
604
|
-
No additional properties.
|
|
605
|
-
|
|
606
|
-
### Usage Shape
|
|
607
|
-
|
|
608
|
-
```ts
|
|
609
|
-
on: {
|
|
610
|
-
press: submitFormData({ ... })
|
|
611
|
-
}
|
|
612
|
-
```
|
|
613
|
-
|
|
614
|
-
## triggerApi
|
|
615
|
-
|
|
616
|
-
Call a Rippling internal API endpoint. Specify method as GET or POST.
|
|
617
|
-
|
|
618
|
-
url: must be a relative Rippling path starting with "/" (e.g. "/api/hr/employees"). Absolute URLs are rejected.
|
|
619
|
-
method: "GET" or "POST" (defaults to "POST"). GET sends payload as query params; POST sends as JSON body.
|
|
620
|
-
payload: for POST, JSON body (defaults to {}). For GET, query parameters (optional).
|
|
621
|
-
responsePath (client-side): stores the response body at that state path.
|
|
622
|
-
|
|
623
|
-
Catalog key: `triggerApi`
|
|
624
|
-
Creator: `triggerApi`
|
|
625
|
-
Params type: `TriggerApiParams`
|
|
626
|
-
|
|
627
|
-
### Params
|
|
628
|
-
|
|
629
|
-
| Name | Required | Type | Description |
|
|
630
|
-
|---|---:|---|---|
|
|
631
|
-
| `errorPath` | no | string | |
|
|
632
|
-
| `method` | yes | [triggerApiMethod](./definitions.md#triggerapimethod) | |
|
|
633
|
-
| `payload` | no | [Payload](./types.md#payload) | |
|
|
634
|
-
| `responsePath` | no | string | |
|
|
635
|
-
| `url` | yes | string | |
|
|
636
|
-
|
|
637
|
-
No additional properties.
|
|
638
|
-
|
|
639
|
-
### Usage Shape
|
|
640
|
-
|
|
641
|
-
```ts
|
|
642
|
-
on: {
|
|
643
|
-
press: triggerApi({ ... })
|
|
644
|
-
}
|
|
645
|
-
```
|