@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,16 @@
1
+ # Pebble SDUI SDK Docs
2
+
3
+ Index for SDK docs. Start with the shared concepts, then choose the SDK language and platform catalog you are authoring with.
4
+
5
+ ## Common Docs
6
+
7
+ - [concepts.md](./concepts.md): Read this first to understand the SDUI mental model: how SDK-authored component trees become JSON specs for JSON-renderer, what catalogs constrain, and how state, expressions, actions, rendering, and raw-spec validation fit together.
8
+ - [catalogs.md](./catalogs.md): Use this to choose language and platform-specific catalog docs.
9
+ - [recipes.md](./recipes.md): Use this to choose language-specific recipes.
10
+
11
+ ## Language Docs
12
+
13
+ | SDK language | Docs |
14
+ |---|---|---|
15
+ | TypeScript | [typescript/README.md](./typescript/README.md) |
16
+ | Python | [python/README.md](./python/README.md) |
@@ -0,0 +1,10 @@
1
+ # Catalogs
2
+
3
+ Catalog docs are platform and language-specific because generated component, action, type, and import surfaces differ by SDK package. Choose the catalog docs for the platform and SDK language you are authoring with.
4
+
5
+ | Platform | SDK language | Catalog index |
6
+ |---|---|---|
7
+ | Web | TypeScript | [typescript/web/catalogs.md](./typescript/web/catalogs.md) |
8
+ | Web | Python | [python/web/catalogs.md](./python/web/catalogs.md) |
9
+ | Mobile | TypeScript | [typescript/mobile/catalogs.md](./typescript/mobile/catalogs.md) |
10
+ | Mobile | Python | [python/mobile/catalogs.md](./python/mobile/catalogs.md) |
@@ -0,0 +1,370 @@
1
+ # Concepts
2
+
3
+ Pebble SDUI is a way to describe a user interface as data. Instead of sending hand-written UI code to the runtime, an author produces a JSON spec. JSON-renderer receives that spec and renders the UI.
4
+
5
+ SDKs exist to make those JSON specs easier and safer to create. An SDK is an authoring layer: it helps authors use known components, props, actions, state references, and expressions, then renders that authored structure into the JSON shape JSON-renderer understands.
6
+
7
+ ## The Big Picture
8
+
9
+ The authoring flow is:
10
+
11
+ 1. Choose one catalog for the target surface.
12
+ 2. Use only components, actions, computed functions, and render helpers from that catalog.
13
+ 3. Define the initial runtime state the UI needs.
14
+ 4. Build a component tree using catalog-backed components.
15
+ 5. Use expressions for runtime state reads, bindings, conditions, templates, and repeats.
16
+ 6. Render the component tree into a JSON spec.
17
+ 7. Send the JSON spec to JSON-renderer.
18
+
19
+ The SDK helps before the spec reaches JSON-renderer. Depending on the SDK language, it can catch authoring mistakes such as unknown props, wrong enum values, wrong event names, invalid action params, invalid state paths, or children passed to leaf components.
20
+
21
+ ## JSON-Renderer
22
+
23
+ JSON-renderer is the runtime. It receives a JSON spec and turns it into UI.
24
+
25
+ JSON-renderer does not run SDK source code. It only sees the rendered JSON spec.
26
+
27
+ That separation is important:
28
+
29
+ - SDKs are for authoring specs.
30
+ - JSON specs are for runtime rendering.
31
+ - JSON-renderer renders specs, not SDK code.
32
+
33
+ ## Spec
34
+
35
+ A spec is the JSON object sent to JSON-renderer.
36
+
37
+ At a high level, a spec contains:
38
+
39
+ - `platform`: the target platform, such as `web` or `mobile`.
40
+ - `catalog`: the catalog name that defines the component and action vocabulary.
41
+ - `catalogVersion`: the catalog version.
42
+ - `root`: the ID of the root element to render.
43
+ - `elements`: a flat map of element ID to element definition.
44
+ - `state`: optional initial runtime state.
45
+
46
+ Example shape:
47
+
48
+ ```json
49
+ {
50
+ "platform": "web",
51
+ "catalog": "custom-apps",
52
+ "catalogVersion": "1.0.0",
53
+ "root": "root",
54
+ "elements": {
55
+ "root": {
56
+ "type": "VStack",
57
+ "props": { "gap": 12 },
58
+ "children": ["title"]
59
+ },
60
+ "title": {
61
+ "type": "Text",
62
+ "props": { "text": "Welcome" }
63
+ }
64
+ },
65
+ "state": {}
66
+ }
67
+ ```
68
+
69
+ Authors usually should not assemble this flat JSON by hand when an SDK is available. The normal path is to build a catalog-backed component tree and render it into this spec shape.
70
+
71
+ ## SDK Authoring Examples
72
+
73
+ The exact imports come from the chosen catalog docs. The examples below show the same authoring idea in TypeScript and Python: build a component tree, then render it into a JSON spec.
74
+
75
+ TypeScript:
76
+
77
+ ```ts
78
+ const root = VStack({
79
+ id: 'root',
80
+ props: {
81
+ gap: 'space200',
82
+ },
83
+ children: [
84
+ Text({
85
+ id: 'title',
86
+ props: {
87
+ text: 'Welcome',
88
+ },
89
+ }),
90
+ ],
91
+ });
92
+
93
+ const spec = render({
94
+ root,
95
+ state: {},
96
+ });
97
+ ```
98
+
99
+ Python:
100
+
101
+ ```python
102
+ root = VStack(
103
+ id="root",
104
+ gap="space200",
105
+ children=[
106
+ Text(
107
+ id="title",
108
+ text="Welcome",
109
+ ),
110
+ ],
111
+ )
112
+
113
+ spec = render(root, {})
114
+ ```
115
+
116
+ ## Catalog
117
+
118
+ A catalog is the vocabulary for a spec. It defines what JSON-renderer can render for a specific surface.
119
+
120
+ A catalog defines:
121
+
122
+ - available components
123
+ - component props
124
+ - component events
125
+ - whether each component accepts children
126
+ - available actions
127
+ - action params
128
+ - computed functions, when supported
129
+ - nested/shared value types
130
+ - enum definitions
131
+ - catalog name and version
132
+
133
+ Create each spec using exactly one catalog. Do not mix components, actions, computed functions, or render helpers from different catalogs.
134
+
135
+ Read [catalogs.md](./catalogs.md) to choose a catalog, then read that catalog's docs before using its components or actions.
136
+
137
+ ## Component
138
+
139
+ A component is a UI building block from a catalog. Examples include layout containers, text, buttons, form inputs, tables, modals, and status indicators.
140
+
141
+ In the rendered spec, each component becomes an element entry:
142
+
143
+ ```json
144
+ {
145
+ "type": "Button",
146
+ "props": {
147
+ "label": "Save",
148
+ "appearance": "PRIMARY"
149
+ },
150
+ "on": {
151
+ "press": {
152
+ "action": "showNotification",
153
+ "params": {
154
+ "message": "Saved",
155
+ "variant": "success"
156
+ }
157
+ }
158
+ }
159
+ }
160
+ ```
161
+
162
+ Common element fields:
163
+
164
+ - `type`: the catalog component name.
165
+ - `props`: component-specific data.
166
+ - `children`: child element IDs, only when the component accepts children.
167
+ - `visible`: boolean or condition controlling visibility.
168
+ - `repeat`: list repetition binding.
169
+ - `on`: event handlers keyed by catalog event name.
170
+
171
+ The catalog component docs define each component's description, additional docs, props, events, and child support.
172
+
173
+ ## Prop
174
+
175
+ A prop is data passed to a component. Props become part of an element in the rendered JSON spec.
176
+
177
+ Props can be literal values:
178
+
179
+ ```json
180
+ {
181
+ "text": "Welcome"
182
+ }
183
+ ```
184
+
185
+ Props can also be runtime expressions:
186
+
187
+ ```json
188
+ {
189
+ "text": { "$state": "/title" }
190
+ }
191
+ ```
192
+
193
+ The catalog defines which props exist, which are required, and which value shapes are allowed.
194
+
195
+ ## Event
196
+
197
+ An event is a named interaction emitted by a component, such as `press`, `change`, or `blur`.
198
+
199
+ Events are component-specific. A button might emit `press`; an input might emit `change` or `blur`. The catalog component docs list the valid events for each component.
200
+
201
+ Events are usually connected to actions.
202
+
203
+ ## Action
204
+
205
+ An action is a side effect triggered by an event.
206
+
207
+ For example, a button `press` event can show a notification:
208
+
209
+ ```json
210
+ {
211
+ "on": {
212
+ "press": {
213
+ "action": "showNotification",
214
+ "params": {
215
+ "message": "Saved",
216
+ "variant": "success"
217
+ }
218
+ }
219
+ }
220
+ }
221
+ ```
222
+
223
+ The catalog action docs define which actions exist and which params each action accepts.
224
+
225
+ Actions may also support shared options such as confirmation, success handling, error handling, or preventing default behavior.
226
+
227
+ ## State
228
+
229
+ State is runtime data available to JSON-renderer. It drives dynamic text, visibility, repeated lists, form values, and action params.
230
+
231
+ State is included in the rendered spec as initial data:
232
+
233
+ ```json
234
+ {
235
+ "state": {
236
+ "user": {
237
+ "name": "Ada"
238
+ },
239
+ "isReady": true
240
+ }
241
+ }
242
+ ```
243
+
244
+ Expressions can read or bind to paths inside this state.
245
+
246
+ ## State Reference
247
+
248
+ A state reference reads a value from runtime state:
249
+
250
+ ```json
251
+ { "$state": "/user/name" }
252
+ ```
253
+
254
+ Use state references when the UI should display or use a runtime value without writing to it.
255
+
256
+ ## Binding
257
+
258
+ A binding is a two-way state reference. It lets input-like components update runtime state:
259
+
260
+ ```json
261
+ { "$bindState": "/form/email" }
262
+ ```
263
+
264
+ Use bindings only when the component should write changes back to state. Use read-only state references for display and comparisons.
265
+
266
+ ## Expression
267
+
268
+ An expression is a runtime-resolved value. Expressions let a JSON spec stay dynamic after it reaches JSON-renderer.
269
+
270
+ Common expression forms:
271
+
272
+ - `$state`: read a state path.
273
+ - `$bindState`: bind to a state path.
274
+ - `$item`: read a repeated item field.
275
+ - `$bindItem`: bind to a repeated item field.
276
+ - `$index`: read the repeat index.
277
+ - `$template`: create a runtime string from refs.
278
+ - `$cond`: choose between values at runtime.
279
+ - `$computed`: call a catalog computed function when available.
280
+
281
+ Expressions appear inside props, visibility, action params, and repeat definitions.
282
+
283
+ ## Condition
284
+
285
+ A condition is an expression used for visibility or conditional values.
286
+
287
+ Example:
288
+
289
+ ```json
290
+ {
291
+ "visible": {
292
+ "$state": "/isReady"
293
+ }
294
+ }
295
+ ```
296
+
297
+ Conditions can also compare values or combine multiple conditions. SDKs usually expose helpers for equality, numeric comparisons, truthy/falsy checks, negation, and logical `and`/`or`.
298
+
299
+ ## Template
300
+
301
+ A template is a runtime string expression.
302
+
303
+ Example:
304
+
305
+ ```json
306
+ {
307
+ "$template": "Hello ${/user/name}"
308
+ }
309
+ ```
310
+
311
+ Use templates when a string prop needs runtime interpolation from state, repeated item fields, or indexes.
312
+
313
+ ## Repeat
314
+
315
+ Repeat renders an element once per item in an array state path.
316
+
317
+ Conceptually, a repeated element says:
318
+
319
+ - which array state path to iterate
320
+ - which field identifies each item, if a key is provided
321
+ - which item fields the repeated element reads or binds
322
+
323
+ Example shape:
324
+
325
+ ```json
326
+ {
327
+ "repeat": {
328
+ "statePath": "/todos",
329
+ "key": "id"
330
+ },
331
+ "props": {
332
+ "text": { "$item": "title" }
333
+ }
334
+ }
335
+ ```
336
+
337
+ Use repeat for dynamic lists instead of manually creating fixed children when the list length comes from runtime data.
338
+
339
+ ## Computed Function
340
+
341
+ A computed function is a catalog-defined helper that produces a runtime value expression. Not every catalog defines computed functions.
342
+
343
+ Computed functions are useful when the runtime needs to derive a value from params rather than read it directly from state.
344
+
345
+ When a catalog has computed functions, read its `computed-functions.md` before using them.
346
+
347
+ ## Rendering
348
+
349
+ Rendering is the step that converts an authored component tree into the JSON spec.
350
+
351
+ The render step:
352
+
353
+ - flattens the component tree into `elements`
354
+ - assigns generated IDs where needed
355
+ - preserves explicit IDs
356
+ - serializes props, actions, expressions, visibility, children, and repeats
357
+ - adds `platform`, `catalog`, and `catalogVersion`
358
+
359
+ After rendering, the output is ordinary JSON data ready for JSON-renderer.
360
+
361
+ ## SDK Checks vs Raw Spec Validation
362
+
363
+ When authoring through an SDK, use the SDK language's normal correctness checks first. For example, a typed SDK can catch many mistakes before rendering a spec.
364
+
365
+ Use catalog `validate(spec)` when you already have raw JSON that was created outside an SDK. Examples include API payloads, migrations, fixtures, or hand-written JSON values.
366
+
367
+ This distinction matters:
368
+
369
+ - SDK-authored specs should be corrected at the SDK source level.
370
+ - Raw JSON specs should be corrected by running `validate(spec)` and fixing validation errors against the catalog docs.
@@ -0,0 +1,8 @@
1
+ # Recipes
2
+
3
+ Recipes are language-specific because the authoring APIs differ by SDK language. Platform-specific component and action details live in catalog docs.
4
+
5
+ | SDK language | Recipes |
6
+ |---|---|
7
+ | TypeScript | [typescript/recipes.md](./typescript/recipes.md) |
8
+ | Python | [python/recipes.md](./python/recipes.md) |
@@ -0,0 +1,17 @@
1
+ # TypeScript SDK Docs
2
+
3
+ Use these docs when authoring SDUI specs with a TypeScript SDK package.
4
+
5
+ ## Core Docs
6
+
7
+ - [../concepts.md](../concepts.md): Shared SDUI concepts.
8
+ - [api-reference.md](./api-reference.md): Core TypeScript SDK interfaces outside generated catalogs.
9
+ - [recipes.md](./recipes.md): Common TypeScript authoring patterns.
10
+ - [catalogs.md](./catalogs.md): Platform-specific TypeScript catalog docs.
11
+
12
+ ## Catalog Docs
13
+
14
+ | Platform | Catalog index |
15
+ |---|---|
16
+ | Web | [web/catalogs.md](./web/catalogs.md) |
17
+ | Mobile | [mobile/catalogs.md](./mobile/catalogs.md) |