@rippling/pebble-sdui-web 0.4.0 → 0.4.2

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.
@@ -0,0 +1,383 @@
1
+ # TypeScript Recipes
2
+
3
+ These recipes show common ways to use JSON-render features through the TypeScript SDK. Each recipe starts from the SDK authoring view and explains what JSON-render receives after `render()`.
4
+
5
+ Before using catalog components or actions, read [./catalogs.md](./catalogs.md) and choose one catalog. The examples below use `@rippling/pebble-sdui-web/catalogs/custom-apps`.
6
+
7
+ ## Create A Spec
8
+
9
+ A spec is the JSON payload sent to JSON-render. In TypeScript, you usually create a typed component tree first, then call the catalog `render()` function to produce that JSON.
10
+
11
+ ```ts
12
+ import { createSpec } from '@rippling/pebble-sdui-web';
13
+ import {
14
+ Button,
15
+ Text,
16
+ VStack,
17
+ render,
18
+ showNotification,
19
+ } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
20
+
21
+ interface AppState {
22
+ title: string;
23
+ }
24
+
25
+ const initialState: AppState = {
26
+ title: 'Welcome',
27
+ };
28
+
29
+ const { $state } = createSpec<AppState>({ state: initialState });
30
+
31
+ const root = VStack({
32
+ id: 'root',
33
+ props: {
34
+ gap: 'space200',
35
+ },
36
+ children: [
37
+ Text({
38
+ props: {
39
+ text: $state('/title'),
40
+ },
41
+ }),
42
+ Button({
43
+ props: {
44
+ label: 'Continue',
45
+ appearance: 'PRIMARY',
46
+ },
47
+ on: {
48
+ press: showNotification({
49
+ message: 'Continuing',
50
+ variant: 'success',
51
+ }),
52
+ },
53
+ }),
54
+ ],
55
+ });
56
+
57
+ const spec = render({
58
+ root,
59
+ state: initialState,
60
+ });
61
+ ```
62
+
63
+ What JSON-render receives:
64
+
65
+ - a flat `elements` map
66
+ - a `root` element ID
67
+ - initial `state`
68
+ - `platform`, `catalog`, and `catalogVersion`
69
+ - serialized action and expression objects
70
+
71
+ Check SDK-authored code with TypeScript:
72
+
73
+ ```sh
74
+ tsc --noEmit
75
+ ```
76
+
77
+ ## Read State In A Prop
78
+
79
+ Use `$state(path)` when JSON-render should read a value from runtime state. The SDK checks that the path exists and that the referenced value is compatible with the prop type.
80
+
81
+ ```ts
82
+ interface AppState {
83
+ user: {
84
+ name: string;
85
+ };
86
+ }
87
+
88
+ const { $state } = createSpec<AppState>({
89
+ state: {
90
+ user: { name: 'Ada' },
91
+ },
92
+ });
93
+
94
+ const title = Text({
95
+ props: {
96
+ text: $state('/user/name'),
97
+ },
98
+ });
99
+ ```
100
+
101
+ Rendered prop shape:
102
+
103
+ ```json
104
+ {
105
+ "text": { "$state": "/user/name" }
106
+ }
107
+ ```
108
+
109
+ Use `$state()` for values that the UI reads but does not edit.
110
+
111
+ ## Bind State From An Input
112
+
113
+ Use `$bindState(path)` when JSON-render should allow a component to write changes back to state. This is for input-like props such as text input values, selected values, toggles, and form fields.
114
+
115
+ ```ts
116
+ interface AppState {
117
+ form: {
118
+ name: string;
119
+ };
120
+ }
121
+
122
+ const { $bindState } = createSpec<AppState>({
123
+ state: {
124
+ form: { name: '' },
125
+ },
126
+ });
127
+
128
+ TextInput({
129
+ props: {
130
+ value: $bindState('/form/name'),
131
+ },
132
+ });
133
+ ```
134
+
135
+ Rendered prop shape:
136
+
137
+ ```json
138
+ {
139
+ "value": { "$bindState": "/form/name" }
140
+ }
141
+ ```
142
+
143
+ Do not use `$bindState()` for read-only display. Use `$state()` instead.
144
+
145
+ ## Build Runtime Strings With Templates
146
+
147
+ Use `$template` when a string prop needs runtime interpolation. JSON-render resolves the template after it receives the spec.
148
+
149
+ ```ts
150
+ const { $state, $template } = createSpec<AppState>({ state });
151
+
152
+ Text({
153
+ props: {
154
+ text: $template`Hello ${$state('/user/name')}`,
155
+ },
156
+ });
157
+ ```
158
+
159
+ Rendered prop shape:
160
+
161
+ ```json
162
+ {
163
+ "text": { "$template": "Hello ${/user/name}" }
164
+ }
165
+ ```
166
+
167
+ Put plain words directly in the template string. Use interpolations only for SDK expression refs.
168
+
169
+ ## Show Or Hide Components With Conditions
170
+
171
+ Use condition helpers for the component `visible` field. JSON-render evaluates the condition at runtime.
172
+
173
+ ```ts
174
+ import { and_, gt, truthy } from '@rippling/pebble-sdui-web';
175
+
176
+ interface AppState {
177
+ isReady: boolean;
178
+ count: number;
179
+ }
180
+
181
+ const { $state } = createSpec<AppState>({
182
+ state: {
183
+ isReady: true,
184
+ count: 3,
185
+ },
186
+ });
187
+
188
+ Text({
189
+ visible: and_(
190
+ truthy($state('/isReady')),
191
+ gt($state('/count'), 0)
192
+ ),
193
+ props: {
194
+ text: 'Ready',
195
+ },
196
+ });
197
+ ```
198
+
199
+ Use numeric comparisons such as `gt`, `gte`, `lt`, and `lte` only with number-compatible refs or values.
200
+
201
+ ## Choose A Runtime Prop Value With `$cond`
202
+
203
+ Use `$cond()` when the component should always render but a prop value should change at runtime.
204
+
205
+ ```ts
206
+ Text({
207
+ props: {
208
+ text: $cond(
209
+ truthy($state('/isReady')),
210
+ 'Ready',
211
+ 'Waiting'
212
+ ),
213
+ },
214
+ });
215
+ ```
216
+
217
+ Rendered prop shape:
218
+
219
+ ```json
220
+ {
221
+ "text": {
222
+ "$cond": { "$state": "/isReady" },
223
+ "$then": "Ready",
224
+ "$else": "Waiting"
225
+ }
226
+ }
227
+ ```
228
+
229
+ Both branches should resolve to the same prop type.
230
+
231
+ ## Repeat Over Runtime Lists
232
+
233
+ Use `repeat(path, key?)` when JSON-render should render one element per item in a state array.
234
+
235
+ ```ts
236
+ interface Todo {
237
+ id: string;
238
+ title: string;
239
+ done: boolean;
240
+ }
241
+
242
+ interface AppState {
243
+ todos: Todo[];
244
+ }
245
+
246
+ const { repeat } = createSpec<AppState>({
247
+ state: {
248
+ todos: [
249
+ { id: '1', title: 'Review docs', done: false },
250
+ ],
251
+ },
252
+ });
253
+
254
+ const [todoRepeat, todo] = repeat('/todos', 'id');
255
+
256
+ Text({
257
+ repeat: todoRepeat,
258
+ props: {
259
+ text: todo.$('title'),
260
+ },
261
+ });
262
+ ```
263
+
264
+ Rendered shape includes:
265
+
266
+ ```json
267
+ {
268
+ "repeat": {
269
+ "statePath": "/todos",
270
+ "key": "id"
271
+ },
272
+ "props": {
273
+ "text": { "$item": "title" }
274
+ }
275
+ }
276
+ ```
277
+
278
+ Use `todo.$bind('field')` only when the repeated component should write back to that item field. Use `todo.$index()` when the UI needs the current item index.
279
+
280
+ ## Use Components From A Catalog
281
+
282
+ Every component comes from the selected catalog. Read [./web/catalogs/custom-apps/components.md](./web/catalogs/custom-apps/components.md) before using a component.
283
+
284
+ ```ts
285
+ Button({
286
+ props: {
287
+ label: 'Save',
288
+ appearance: 'PRIMARY',
289
+ },
290
+ on: {
291
+ press: showNotification({
292
+ message: 'Saved',
293
+ variant: 'success',
294
+ }),
295
+ },
296
+ });
297
+ ```
298
+
299
+ Rules:
300
+
301
+ - Use only documented props.
302
+ - Include required props.
303
+ - Use only documented event names.
304
+ - Pass `children` only when the component accepts children.
305
+ - Use enum values from linked definitions in `definitions.md`.
306
+
307
+ ## Use Actions From A Catalog
308
+
309
+ Actions are side effects triggered by component events. Use generated action creators instead of raw action dictionaries.
310
+
311
+ ```ts
312
+ import { Button, navigate } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
313
+
314
+ Button({
315
+ props: {
316
+ label: 'Open settings',
317
+ },
318
+ on: {
319
+ press: navigate({
320
+ path: '/custom-apps/app_123/sdui/settings',
321
+ }),
322
+ },
323
+ });
324
+ ```
325
+
326
+ Read [./web/catalogs/custom-apps/actions.md](./web/catalogs/custom-apps/actions.md) for action params and docs.
327
+
328
+ ## Add Confirmation To An Action
329
+
330
+ Generated action creators accept shared action options. Use `confirm` when JSON-render should ask the user before executing an action.
331
+
332
+ ```ts
333
+ Button({
334
+ props: {
335
+ label: 'Delete',
336
+ appearance: 'DESTRUCTIVE',
337
+ },
338
+ on: {
339
+ press: setState(
340
+ {
341
+ statePath: '/deleted',
342
+ value: true,
343
+ },
344
+ {
345
+ confirm: {
346
+ title: 'Delete record?',
347
+ message: 'This cannot be undone.',
348
+ confirmLabel: 'Delete',
349
+ cancelLabel: 'Cancel',
350
+ variant: 'danger',
351
+ },
352
+ }
353
+ ),
354
+ },
355
+ });
356
+ ```
357
+
358
+ Use `onSuccess`, `onError`, and `preventDefault` when the runtime behavior needs follow-up actions or default event suppression.
359
+
360
+ ## Validate A Raw JSON Spec
361
+
362
+ Use `validate(spec)` only for raw JSON/API specs created outside the SDK. Do not use it as the main feedback loop for SDK-authored TypeScript code.
363
+
364
+ ```ts
365
+ import { validate } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
366
+
367
+ const errors = validate(candidateSpec);
368
+
369
+ if (errors.length > 0) {
370
+ return {
371
+ status: 'invalid',
372
+ validationErrors: errors,
373
+ };
374
+ }
375
+
376
+ return {
377
+ status: 'valid',
378
+ spec: candidateSpec,
379
+ validationErrors: [],
380
+ };
381
+ ```
382
+
383
+ Repair raw JSON validation errors by reading the relevant catalog docs and changing the raw spec to match documented component, prop, event, action, type, and enum names.
@@ -0,0 +1,165 @@
1
+ <!-- Auto-generated from catalogs/custom-apps.catalog.json; do not edit directly. -->
2
+ # custom-apps Actions
3
+
4
+ Import action creators from `@rippling/pebble-sdui-web/catalogs/custom-apps`. Read [definitions.md](./definitions.md) for enum values linked from param tables.
5
+
6
+ ## navigate
7
+
8
+ Navigate to a URL path.
9
+
10
+ Page URLs: `/custom-apps/{app_id}/sdui/{page_id}`. Use openInNewTab for external links.
11
+
12
+ Catalog key: `navigate`
13
+ Creator: `navigate`
14
+ Params type: `NavigateParams`
15
+
16
+ ### Params
17
+
18
+ | Name | Required | Type | Description |
19
+ |---|---:|---|---|
20
+ | `openInNewTab` | no | boolean | |
21
+ | `path` | yes | string | |
22
+
23
+ No additional properties.
24
+
25
+ ### Usage Shape
26
+
27
+ ```ts
28
+ on: {
29
+ press: navigate({ ... })
30
+ }
31
+ ```
32
+
33
+ ## pushState
34
+
35
+ Append an item to an array in state. Optionally clear another state path.
36
+
37
+ Catalog key: `pushState`
38
+ Creator: `pushState`
39
+ Params type: `PushStateParams`
40
+
41
+ ### Params
42
+
43
+ | Name | Required | Type | Description |
44
+ |---|---:|---|---|
45
+ | `clearStatePath` | no | string | |
46
+ | `statePath` | yes | string | |
47
+ | `value` | yes | unknown | |
48
+
49
+ No additional properties.
50
+
51
+ ### Usage Shape
52
+
53
+ ```ts
54
+ on: {
55
+ press: pushState({ ... })
56
+ }
57
+ ```
58
+
59
+ ## removeState
60
+
61
+ Remove an item from an array in state by index.
62
+
63
+ Catalog key: `removeState`
64
+ Creator: `removeState`
65
+ Params type: `RemoveStateParams`
66
+
67
+ ### Params
68
+
69
+ | Name | Required | Type | Description |
70
+ |---|---:|---|---|
71
+ | `index` | yes | number | |
72
+ | `statePath` | yes | string | |
73
+
74
+ No additional properties.
75
+
76
+ ### Usage Shape
77
+
78
+ ```ts
79
+ on: {
80
+ press: removeState({ ... })
81
+ }
82
+ ```
83
+
84
+ ## setState
85
+
86
+ Update a value in the state model at the given statePath.
87
+
88
+ Catalog key: `setState`
89
+ Creator: `setState`
90
+ Params type: `SetStateParams`
91
+
92
+ ### Params
93
+
94
+ | Name | Required | Type | Description |
95
+ |---|---:|---|---|
96
+ | `statePath` | yes | string | |
97
+ | `value` | yes | unknown | |
98
+
99
+ No additional properties.
100
+
101
+ ### Usage Shape
102
+
103
+ ```ts
104
+ on: {
105
+ press: setState({ ... })
106
+ }
107
+ ```
108
+
109
+ ## showNotification
110
+
111
+ Show a toast notification. Auto-dismisses after 7 seconds.
112
+
113
+ Catalog key: `showNotification`
114
+ Creator: `showNotification`
115
+ Params type: `ShowNotificationParams`
116
+
117
+ ### Params
118
+
119
+ | Name | Required | Type | Description |
120
+ |---|---:|---|---|
121
+ | `message` | yes | string | |
122
+ | `variant` | yes | [showNotificationVariant](./definitions.md#shownotificationvariant) | |
123
+
124
+ No additional properties.
125
+
126
+ ### Usage Shape
127
+
128
+ ```ts
129
+ on: {
130
+ press: showNotification({ ... })
131
+ }
132
+ ```
133
+
134
+ ## triggerFunction
135
+
136
+ Call a Rippling Function. Extra params are sent as event.parameters.
137
+
138
+ responsePath (client-side): stores response body at that state path. Body must match the state shape (e.g. array, NOT wrapped in { data: [...] }).
139
+ onSuccess (client-side): runs after handler resolves. Must use { set: { "/path": value } } format, NOT actions.set().
140
+ onError (client-side): runs if handler throws. Same format as onSuccess.
141
+ Extra params (beyond functionId, action, responsePath, onSuccess, onError) are sent to the server as event.parameters.
142
+
143
+ Catalog key: `triggerFunction`
144
+ Creator: `triggerFunction`
145
+ Params type: `TriggerFunctionParams`
146
+
147
+ ### Params
148
+
149
+ | Name | Required | Type | Description |
150
+ |---|---:|---|---|
151
+ | `action` | yes | string | |
152
+ | `functionId` | yes | string | |
153
+ | `onError` | no | unknown | |
154
+ | `onSuccess` | no | unknown | |
155
+ | `responsePath` | no | string | |
156
+
157
+ No additional properties.
158
+
159
+ ### Usage Shape
160
+
161
+ ```ts
162
+ on: {
163
+ press: triggerFunction({ ... })
164
+ }
165
+ ```