@rippling/pebble-sdui-web 0.4.1 → 0.6.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,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) |