@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.
- package/dist/catalogs/custom-apps/catalog.d.ts +5 -1
- package/dist/catalogs/custom-apps/component-props.d.ts +56 -68
- package/dist/catalogs/custom-apps/index.cjs +8 -8
- package/dist/catalogs/custom-apps/index.cjs.map +1 -1
- package/dist/catalogs/custom-apps/index.d.ts +2 -2
- package/dist/catalogs/custom-apps/index.js +8841 -4827
- package/dist/catalogs/custom-apps/index.js.map +1 -1
- package/dist/docs/README.md +16 -0
- package/dist/docs/catalogs.md +10 -0
- package/dist/docs/concepts.md +370 -0
- package/dist/docs/recipes.md +8 -0
- package/dist/docs/typescript/README.md +17 -0
- package/dist/docs/typescript/api-reference.md +400 -0
- package/dist/docs/typescript/catalogs.md +8 -0
- package/dist/docs/typescript/recipes.md +383 -0
- package/dist/docs/typescript/web/catalogs/custom-apps/actions.md +165 -0
- package/dist/docs/typescript/web/catalogs/custom-apps/components.md +6184 -0
- package/dist/docs/typescript/web/catalogs/custom-apps/computed-functions.md +6 -0
- package/dist/docs/typescript/web/catalogs/custom-apps/definitions.md +3573 -0
- package/dist/docs/typescript/web/catalogs/custom-apps/readme.md +16 -0
- package/dist/docs/typescript/web/catalogs/custom-apps/types.md +2507 -0
- package/dist/docs/typescript/web/catalogs.md +7 -0
- package/dist/sdk-docs.cjs +40 -9
- package/dist/sdk-docs.cjs.map +1 -1
- package/dist/sdk-docs.js +41 -10
- package/dist/sdk-docs.js.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,400 @@
|
|
|
1
|
+
# API Reference
|
|
2
|
+
|
|
3
|
+
This page lists the core TypeScript SDK surface exported from `@rippling/pebble-sdui-web`, apart from catalog-specific component builders, action creators, and computed functions.
|
|
4
|
+
|
|
5
|
+
Catalog-specific APIs are documented from [./catalogs.md](./catalogs.md).
|
|
6
|
+
|
|
7
|
+
## `createSpec<State>({ state })`
|
|
8
|
+
|
|
9
|
+
Creates typed helpers for a state model.
|
|
10
|
+
|
|
11
|
+
Purpose:
|
|
12
|
+
|
|
13
|
+
- type-check state paths
|
|
14
|
+
- create runtime refs and bindings
|
|
15
|
+
- create templates and conditional expressions
|
|
16
|
+
- create repeat bindings
|
|
17
|
+
- optionally render a core-only tree
|
|
18
|
+
|
|
19
|
+
✅ Correct:
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
interface AppState {
|
|
23
|
+
user: { name: string };
|
|
24
|
+
isReady: boolean;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
const { $state } = createSpec<AppState>({
|
|
28
|
+
state: {
|
|
29
|
+
user: { name: 'Ada' },
|
|
30
|
+
isReady: true,
|
|
31
|
+
},
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
$state('/user/name');
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
❌ Incorrect:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
$state('/user/missing');
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Why it fails: `'/user/missing'` is not a valid `StatePaths<AppState>` path.
|
|
44
|
+
|
|
45
|
+
## `$state(path)`
|
|
46
|
+
|
|
47
|
+
Creates a read-only state reference.
|
|
48
|
+
|
|
49
|
+
Purpose:
|
|
50
|
+
|
|
51
|
+
- read runtime state in props, action params, conditions, and templates
|
|
52
|
+
- preserve the resolved TypeScript type of the state path
|
|
53
|
+
|
|
54
|
+
✅ Correct:
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
const title = Text({
|
|
58
|
+
props: {
|
|
59
|
+
text: $state('/user/name'),
|
|
60
|
+
},
|
|
61
|
+
});
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
❌ Incorrect:
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
const title = Text({
|
|
68
|
+
props: {
|
|
69
|
+
text: $state('/isReady'),
|
|
70
|
+
},
|
|
71
|
+
});
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Why it fails: `Text.text` expects a string-compatible value, but `/isReady` resolves to boolean.
|
|
75
|
+
|
|
76
|
+
## `$bindState(path)`
|
|
77
|
+
|
|
78
|
+
Creates a two-way binding to a state path.
|
|
79
|
+
|
|
80
|
+
Purpose:
|
|
81
|
+
|
|
82
|
+
- let input-like components write values back to runtime state
|
|
83
|
+
- preserve the resolved TypeScript type of the bound state path
|
|
84
|
+
|
|
85
|
+
✅ Correct:
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
TextInput({
|
|
89
|
+
props: {
|
|
90
|
+
value: $bindState('/form/name'),
|
|
91
|
+
},
|
|
92
|
+
});
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
❌ Incorrect:
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
TextInput({
|
|
99
|
+
props: {
|
|
100
|
+
value: $bindState('/form/count'),
|
|
101
|
+
},
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Why it fails: a text input value expects a string-compatible binding, but `/form/count` resolves to number.
|
|
106
|
+
|
|
107
|
+
## `$template`
|
|
108
|
+
|
|
109
|
+
Creates a string expression from refs.
|
|
110
|
+
|
|
111
|
+
Purpose:
|
|
112
|
+
|
|
113
|
+
- build runtime strings from state, repeat item refs, or repeat indexes
|
|
114
|
+
- serialize as a JSON-renderer `$template` expression
|
|
115
|
+
|
|
116
|
+
✅ Correct:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
Text({
|
|
120
|
+
props: {
|
|
121
|
+
text: $template`Hello ${$state('/user/name')}`,
|
|
122
|
+
},
|
|
123
|
+
});
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
❌ Incorrect:
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
Text({
|
|
130
|
+
props: {
|
|
131
|
+
text: $template`Hello ${'Ada'}`,
|
|
132
|
+
},
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Why it fails: template interpolations accept expression refs, `null`, or `undefined`; plain literal interpolation is not part of the typed surface.
|
|
137
|
+
|
|
138
|
+
## `$cond(condition, thenValue, elseValue)`
|
|
139
|
+
|
|
140
|
+
Creates a conditional runtime expression.
|
|
141
|
+
|
|
142
|
+
Purpose:
|
|
143
|
+
|
|
144
|
+
- choose a prop value at runtime based on a condition
|
|
145
|
+
- enforce compatible branch value types
|
|
146
|
+
|
|
147
|
+
✅ Correct:
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
Text({
|
|
151
|
+
props: {
|
|
152
|
+
text: $cond(truthy($state('/isReady')), 'Ready', 'Waiting'),
|
|
153
|
+
},
|
|
154
|
+
});
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
❌ Incorrect:
|
|
158
|
+
|
|
159
|
+
```ts
|
|
160
|
+
Text({
|
|
161
|
+
props: {
|
|
162
|
+
text: $cond(truthy($state('/isReady')), 'Ready', 0),
|
|
163
|
+
},
|
|
164
|
+
});
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Why it fails: both branches must resolve to the prop's expected type.
|
|
168
|
+
|
|
169
|
+
## `repeat(path, key?)`
|
|
170
|
+
|
|
171
|
+
Creates a repeat binding and item accessor for an array state path.
|
|
172
|
+
|
|
173
|
+
Purpose:
|
|
174
|
+
|
|
175
|
+
- render one element per item in a runtime array
|
|
176
|
+
- access repeated item fields with `item.$()`
|
|
177
|
+
- bind repeated item fields with `item.$bind()`
|
|
178
|
+
- access repeat index with `item.$index()`
|
|
179
|
+
|
|
180
|
+
✅ Correct:
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
interface AppState {
|
|
184
|
+
todos: { id: string; title: string; done: boolean }[];
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
const [todoRepeat, todo] = repeat('/todos', 'id');
|
|
188
|
+
|
|
189
|
+
Text({
|
|
190
|
+
repeat: todoRepeat,
|
|
191
|
+
props: {
|
|
192
|
+
text: todo.$('title'),
|
|
193
|
+
},
|
|
194
|
+
});
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
❌ Incorrect:
|
|
198
|
+
|
|
199
|
+
```ts
|
|
200
|
+
repeat('/user/name');
|
|
201
|
+
todo.$('missing');
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
Why it fails: `repeat()` only accepts array-valued state paths, and item accessors only accept paths that exist on the array item type.
|
|
205
|
+
|
|
206
|
+
## Conditions
|
|
207
|
+
|
|
208
|
+
Condition helpers create `VisibilityBinding` values for `visible` and `$cond()`.
|
|
209
|
+
|
|
210
|
+
Exports:
|
|
211
|
+
|
|
212
|
+
- `$when(ref, ops?)`
|
|
213
|
+
- `equals(ref, value)`
|
|
214
|
+
- `neq(ref, value)`
|
|
215
|
+
- `gt(ref, value)`
|
|
216
|
+
- `gte(ref, value)`
|
|
217
|
+
- `lt(ref, value)`
|
|
218
|
+
- `lte(ref, value)`
|
|
219
|
+
- `truthy(ref)`
|
|
220
|
+
- `falsy(ref)`
|
|
221
|
+
- `not_(condition)`
|
|
222
|
+
- `$and(...conditions)` / `and_(...conditions)`
|
|
223
|
+
- `$or(...conditions)` / `or_(...conditions)`
|
|
224
|
+
|
|
225
|
+
✅ Correct:
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
const visible = and_(
|
|
229
|
+
truthy($state('/isReady')),
|
|
230
|
+
gt($state('/count'), 0)
|
|
231
|
+
);
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
❌ Incorrect:
|
|
235
|
+
|
|
236
|
+
```ts
|
|
237
|
+
gt($state('/user/name'), 0);
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Why it fails: greater-than comparisons require a number literal or number state ref.
|
|
241
|
+
|
|
242
|
+
## `PropValue<T>` And `WrapWithPropValue<TProps>`
|
|
243
|
+
|
|
244
|
+
Generated component prop types are wrapped so each prop accepts either a literal value or a compatible runtime expression.
|
|
245
|
+
|
|
246
|
+
Purpose:
|
|
247
|
+
|
|
248
|
+
- allow `Text.text` to accept `string`, `StateRef<string>`, `TemplateRef`, `CondRef<string>`, or compatible computed refs
|
|
249
|
+
- reject expression refs that resolve to the wrong type
|
|
250
|
+
|
|
251
|
+
✅ Correct:
|
|
252
|
+
|
|
253
|
+
```ts
|
|
254
|
+
Text({
|
|
255
|
+
props: {
|
|
256
|
+
text: $state('/user/name'),
|
|
257
|
+
},
|
|
258
|
+
});
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
❌ Incorrect:
|
|
262
|
+
|
|
263
|
+
```ts
|
|
264
|
+
Text({
|
|
265
|
+
props: {
|
|
266
|
+
text: $state('/count'),
|
|
267
|
+
},
|
|
268
|
+
});
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Why it fails: `/count` resolves to number, not string.
|
|
272
|
+
|
|
273
|
+
## `ActionParamValue<T>` And `WrapWithActionParamValue<TParams>`
|
|
274
|
+
|
|
275
|
+
Generated action param types are wrapped so params accept literals or read-only compatible expressions.
|
|
276
|
+
|
|
277
|
+
Purpose:
|
|
278
|
+
|
|
279
|
+
- allow action params to read state or repeat item values
|
|
280
|
+
- prevent two-way binding refs as action params
|
|
281
|
+
|
|
282
|
+
✅ Correct:
|
|
283
|
+
|
|
284
|
+
```ts
|
|
285
|
+
setState({
|
|
286
|
+
statePath: '/selectedId',
|
|
287
|
+
value: item.$('id'),
|
|
288
|
+
});
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
❌ Incorrect:
|
|
292
|
+
|
|
293
|
+
```ts
|
|
294
|
+
setState({
|
|
295
|
+
statePath: '/selectedId',
|
|
296
|
+
value: $bindState('/selectedId'),
|
|
297
|
+
});
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
Why it fails: action params use read-only expression values, not binding refs.
|
|
301
|
+
|
|
302
|
+
## `ActionOptions`
|
|
303
|
+
|
|
304
|
+
Shared options accepted by generated action creators.
|
|
305
|
+
|
|
306
|
+
Fields:
|
|
307
|
+
|
|
308
|
+
- `confirm`: confirmation dialog before executing an action
|
|
309
|
+
- `onSuccess`: handler after action success
|
|
310
|
+
- `onError`: handler after action failure
|
|
311
|
+
- `preventDefault`: prevent the default component behavior when supported
|
|
312
|
+
|
|
313
|
+
✅ Correct:
|
|
314
|
+
|
|
315
|
+
```ts
|
|
316
|
+
setState(
|
|
317
|
+
{ statePath: '/deleted', value: true },
|
|
318
|
+
{
|
|
319
|
+
confirm: {
|
|
320
|
+
title: 'Delete record?',
|
|
321
|
+
message: 'This cannot be undone.',
|
|
322
|
+
variant: 'danger',
|
|
323
|
+
},
|
|
324
|
+
}
|
|
325
|
+
);
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
❌ Incorrect:
|
|
329
|
+
|
|
330
|
+
```ts
|
|
331
|
+
setState(
|
|
332
|
+
{ statePath: '/deleted', value: true },
|
|
333
|
+
{
|
|
334
|
+
confirm: {
|
|
335
|
+
title: 'Delete record?',
|
|
336
|
+
variant: 'warning',
|
|
337
|
+
},
|
|
338
|
+
}
|
|
339
|
+
);
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
Why it fails: `confirm.message` is required and `confirm.variant` must be `default` or `danger`.
|
|
343
|
+
|
|
344
|
+
## Component Input Types
|
|
345
|
+
|
|
346
|
+
Generated component builders use `ComponentInputs` or `ComponentInputsOptionalProps`.
|
|
347
|
+
|
|
348
|
+
Purpose:
|
|
349
|
+
|
|
350
|
+
- require props when the component has required props
|
|
351
|
+
- allow `on` only for documented event names
|
|
352
|
+
- allow `children` only when the component accepts children
|
|
353
|
+
|
|
354
|
+
✅ Correct:
|
|
355
|
+
|
|
356
|
+
```ts
|
|
357
|
+
Button({
|
|
358
|
+
props: { label: 'Save' },
|
|
359
|
+
on: {
|
|
360
|
+
press: showNotification({ message: 'Saved', variant: 'success' }),
|
|
361
|
+
},
|
|
362
|
+
});
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
❌ Incorrect:
|
|
366
|
+
|
|
367
|
+
```ts
|
|
368
|
+
Button({
|
|
369
|
+
props: { label: 'Save' },
|
|
370
|
+
children: [Text({ props: { text: 'Child' } })],
|
|
371
|
+
});
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
Why it fails: `Button` is a leaf component in the catalog and does not accept children.
|
|
375
|
+
|
|
376
|
+
## Path Types
|
|
377
|
+
|
|
378
|
+
Path helper types are exported for advanced authoring and library code.
|
|
379
|
+
|
|
380
|
+
Exports:
|
|
381
|
+
|
|
382
|
+
- `StatePaths<T>`: valid JSON-pointer state paths
|
|
383
|
+
- `ValueAt<T, P>`: value type at a state path
|
|
384
|
+
- `ArrayPaths<T>`: state paths whose value is an array
|
|
385
|
+
- `ArrayItemAt<T, P>`: item type at an array state path
|
|
386
|
+
- `ItemPaths<T>`: valid slash paths inside a repeated item
|
|
387
|
+
- `ItemValueAt<T, P>`: value type at a repeated item path
|
|
388
|
+
|
|
389
|
+
Most app authors use these indirectly through `createSpec`.
|
|
390
|
+
|
|
391
|
+
## Spec Types
|
|
392
|
+
|
|
393
|
+
Exports:
|
|
394
|
+
|
|
395
|
+
- `FlatSpec`
|
|
396
|
+
- `FlatUIElement`
|
|
397
|
+
- `Spec`
|
|
398
|
+
- `CoreSpec`
|
|
399
|
+
|
|
400
|
+
Use these for service boundaries, tests, or code that stores rendered specs. For app authoring, prefer catalog `render({ root, state })`.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# TypeScript Catalogs
|
|
2
|
+
|
|
3
|
+
Catalog docs are platform-specific because generated component, action, type, and import surfaces differ by SDK package. Choose the catalog docs for the platform you are authoring with.
|
|
4
|
+
|
|
5
|
+
| Platform | Catalog index |
|
|
6
|
+
|---|---|
|
|
7
|
+
| Web | [web/catalogs.md](./web/catalogs.md) |
|
|
8
|
+
| Mobile | [mobile/catalogs.md](./mobile/catalogs.md) |
|