@rippling/pebble-sdui-web 0.2.0 → 0.3.1

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,1115 @@
1
+ "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=[{key:"shared.readme",filePath:"sdk-docs/README.md",title:"Pebble Kit SDK documentation"},{key:"shared.ai-authoring",filePath:"sdk-docs/ai-authoring.md",title:"AI authoring guide"},{key:"shared.catalogs",filePath:"sdk-docs/catalogs.md",title:"Catalogs"},{key:"shared.concepts",filePath:"sdk-docs/concepts.md",title:"Concepts"},{key:"shared.validation",filePath:"sdk-docs/validation.md",title:"Validation"},{key:"typescript.readme",filePath:"sdk-docs/typescript/README.md",title:"TypeScript SDK"},{key:"typescript.components-actions-rendering",filePath:"sdk-docs/typescript/components-actions-rendering.md",title:"TypeScript components, actions, and rendering"},{key:"typescript.state-expressions",filePath:"sdk-docs/typescript/state-expressions.md",title:"TypeScript state and expressions"}],n={"sdk-docs/README.md":`# Pebble Kit SDK documentation
2
+
3
+ Pebble Kit is a server-driven UI (SDUI) SDK for producing JSON specs that the \`json-render\` runtime can render. The SDK is designed for two authors:
4
+
5
+ - **Humans** write typed Python or TypeScript code, compose component trees, bind props to state, and render a validated spec.
6
+ - **LLMs** use catalog metadata, examples, and validation errors to generate SDK code or JSON specs safely, then iterate until validation passes.
7
+
8
+ This documentation focuses on the public authoring model: catalogs, components, actions, state expressions, rendering, and validation.
9
+
10
+ ## What the SDK does
11
+
12
+ The SDK lets an author describe UI as a tree:
13
+
14
+ 1. Choose a platform package, such as \`pebble_sdui_web\` or \`pebble_sdui_mobile\`.
15
+ 2. Import a generated catalog module, such as \`pebble_sdui_web.catalogs.AiChatCatalogV1\`.
16
+ 3. Define initial state with plain annotated Python classes.
17
+ 4. Create components and wire events to generated action creators.
18
+ 5. Use expressions (\`$state\`, \`$bindState\`, \`$item\`, \`$cond\`, \`$template\`) for runtime behavior.
19
+ 6. Call the catalog \`render()\` function to produce the flat JSON wire format.
20
+ 7. Call the catalog \`validate()\` function when specs may be generated or transformed.
21
+
22
+ ## Documentation map
23
+
24
+ These links point to the canonical files in the repo so they still work when this README is shown inside another site or tool.
25
+
26
+ - [ai-authoring.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/ai-authoring.md) — how to prompt and constrain LLM authors.
27
+ - [concepts.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/concepts.md) — core SDUI concepts shared by humans and LLMs.
28
+ - [catalogs.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/catalogs.md) — generated catalogs, component discovery, and action discovery.
29
+ - [validation.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/validation.md) — validation workflow and error repair loop.
30
+ - [python/README.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/python/README.md) — Python SDK quick start.
31
+ - [python/components-actions-rendering.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/python/components-actions-rendering.md) — Python components, events, actions, and render output.
32
+ - [python/state-expressions.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/python/state-expressions.md) — Python state, refs, repeat, templates, conditions, and conditional expressions.
33
+ - [typescript/README.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/typescript/README.md) — TypeScript SDK quick start.
34
+ - [typescript/components-actions-rendering.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/typescript/components-actions-rendering.md) — TypeScript components, events, actions, and render output.
35
+ - [typescript/state-expressions.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/typescript/state-expressions.md) — TypeScript state, refs, repeat, templates, conditions, and conditional expressions.
36
+
37
+ ## Quick Python example
38
+
39
+ \`\`\`python
40
+ from pebble_sdui_web import create_state, template, truthy
41
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import (
42
+ ConfirmationCard,
43
+ render,
44
+ submit_tool_output,
45
+ validate,
46
+ )
47
+
48
+ class AppState:
49
+ employee_name: str
50
+ is_ready: bool
51
+
52
+ state = create_state(AppState, {
53
+ "employee_name": "Alice Nguyen",
54
+ "is_ready": True,
55
+ })
56
+
57
+ root = ConfirmationCard(
58
+ id="confirm-employee",
59
+ question=template("Confirm action for ", state.ref(lambda s: s.employee_name), "?"),
60
+ description="This choice will be submitted back to the workflow.",
61
+ events={
62
+ "confirm": submit_tool_output(output={"confirmed": True}),
63
+ "cancel": submit_tool_output(output={"confirmed": False}),
64
+ },
65
+ visible=truthy(state.ref(lambda s: s.is_ready)),
66
+ )
67
+
68
+ spec = render(root, state.to_dict())
69
+ errors = validate(spec)
70
+ assert errors == [], errors
71
+ \`\`\`
72
+
73
+ ## Authoring guidance
74
+
75
+ For humans:
76
+
77
+ - Prefer SDK builders over hand-writing JSON.
78
+ - Let type checkers catch prop, event, and state reference mistakes early.
79
+ - Keep state explicit and small; pass only data the rendered UI needs.
80
+ - Use catalog \`validate()\` before returning specs from untrusted or generated paths.
81
+
82
+ For LLMs:
83
+
84
+ - First inspect the target catalog with \`get_components()\`, \`get_component()\`, \`get_actions()\`, and \`get_action()\`.
85
+ - Generate a small component tree before adding dynamic behavior.
86
+ - Never invent component names, prop names, event names, or action names.
87
+ - Run \`validate(spec)\` and repair from the returned error messages.
88
+ - Prefer SDK code generation over raw JSON because the SDK handles IDs, refs, and serialization.
89
+ `,"sdk-docs/ai-authoring.md":`# AI authoring guide
90
+
91
+ This guide explains how an LLM should use the SDK and catalog metadata to produce correct SDUI specs. It is also useful for humans building agent workflows around Pebble Kit.
92
+
93
+ ## Recommended LLM workflow
94
+
95
+ Prefer this loop:
96
+
97
+ 1. **Identify target platform and catalog.** Example: web + \`AiChatCatalogV1\`.
98
+ 2. **Inspect catalog capabilities.** Use \`get_components()\`, \`get_component()\`, \`get_actions()\`, and \`get_action()\`.
99
+ 3. **Plan a small tree.** Pick the root and children. Confirm each component supports children before nesting.
100
+ 4. **Generate SDK code, not raw JSON.** SDK code gives better type hints and automatic serialization.
101
+ 5. **Render.** Call the catalog \`render(root, state)\`.
102
+ 6. **Validate.** Call the catalog \`validate(spec)\`.
103
+ 7. **Repair from errors.** Treat validation errors as the next prompt context.
104
+ 8. **Return the spec or checked-in code.** Include validation status.
105
+
106
+ ## Why SDK code is better than raw JSON
107
+
108
+ SDK code avoids common LLM mistakes:
109
+
110
+ - element IDs are generated or checked for duplicates
111
+ - component props are spelled by generated dataclass fields
112
+ - action creators serialize params correctly
113
+ - state refs serialize as \`$state\`, \`$bindState\`, \`$item\`, and \`$index\`
114
+ - catalog renderers add platform/catalog metadata
115
+ - validation catches schema and structural problems
116
+
117
+ Raw JSON is acceptable only when an integration cannot execute SDK code. In that mode, the LLM must still use catalog definitions and \`validate()\`.
118
+
119
+ ## Prompt pattern for LLMs
120
+
121
+ Use a prompt like this when asking an LLM to author a UI:
122
+
123
+ \`\`\`text
124
+ You are authoring a Pebble Kit SDUI spec.
125
+ Target package: pebble_sdui_web
126
+ Target catalog: pebble_sdui_web.catalogs.AiChatCatalogV1
127
+
128
+ Rules:
129
+ - Use only components returned by get_components().
130
+ - Before using a component, inspect get_component(name).
131
+ - Use only props defined in propsSchema.
132
+ - Include all required props.
133
+ - Use only events listed by the component definition.
134
+ - Use only actions returned by get_actions().
135
+ - Prefer generated SDK code over hand-written JSON.
136
+ - Call render(root, state) and then validate(spec).
137
+ - If validate returns errors, fix the code and validate again.
138
+
139
+ User goal:
140
+ <goal here>
141
+ \`\`\`
142
+
143
+ ## Minimal executable harness
144
+
145
+ \`\`\`python
146
+ from pebble_sdui_web import create_state
147
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import (
148
+ ConfirmationCard,
149
+ render,
150
+ submit_tool_output,
151
+ validate,
152
+ )
153
+
154
+ class AppState:
155
+ is_ready: bool
156
+
157
+ state = create_state(AppState, {"is_ready": True})
158
+
159
+ root = ConfirmationCard(
160
+ question="Do you want to continue?",
161
+ events={"confirm": submit_tool_output(output="yes")},
162
+ )
163
+
164
+ spec = render(root, state.to_dict())
165
+ errors = validate(spec)
166
+ if errors:
167
+ raise ValueError("Invalid spec:\\n" + "\\n".join(errors))
168
+ \`\`\`
169
+
170
+ ## Repair loop
171
+
172
+ When validation fails, preserve the full error text. Then ask the model to make the smallest change that fixes the first error.
173
+
174
+ Example repair prompt:
175
+
176
+ \`\`\`text
177
+ The spec failed validation:
178
+ - Element 'confirm': unknown event 'submit'. Valid: ['confirm', 'cancel']
179
+
180
+ Fix the SDK code. Do not change the user's intent. Do not invent new events.
181
+ \`\`\`
182
+
183
+ Repair strategy:
184
+
185
+ - Unknown component: choose a component from \`get_components()\`.
186
+ - Unknown prop: remove it or map it to a documented prop from \`propsSchema\`.
187
+ - Missing required prop: add the prop with a safe value or state ref.
188
+ - Unknown event: use one of the component's listed events.
189
+ - Unknown action: use one from \`get_actions()\`.
190
+ - Children not accepted: remove children or choose a container component.
191
+ - Root missing: render the actual root returned by the tree.
192
+
193
+ ## LLM safety rules
194
+
195
+ An LLM should not:
196
+
197
+ - invent schema fields because they sound plausible
198
+ - depend on undocumented renderer behavior
199
+ - manually serialize Python SDK objects unless using \`render()\` helpers
200
+ - mix components from different catalogs
201
+ - output a spec without reporting validation status
202
+ - ignore validation errors because the UI “looks close”
203
+
204
+ ## Human review checklist for AI-authored specs
205
+
206
+ Before accepting an AI-authored spec, check:
207
+
208
+ - Does the UI satisfy the user goal with the smallest reasonable tree?
209
+ - Are all component names, props, events, and actions catalog-backed?
210
+ - Is state minimal and free of sensitive data not needed by the UI?
211
+ - Are bindings used only for data the UI should write back?
212
+ - Are action payloads safe and expected by the receiving workflow?
213
+ - Did \`validate(spec)\` return \`[]\`?
214
+
215
+ ## Good output format from an AI authoring service
216
+
217
+ \`\`\`json
218
+ {
219
+ "status": "valid",
220
+ "catalog": "AiChatCatalogV1",
221
+ "catalogVersion": "1.0.0",
222
+ "spec": { "root": "...", "elements": {}, "state": {} },
223
+ "validationErrors": []
224
+ }
225
+ \`\`\`
226
+
227
+ If invalid, return the errors and do not send the spec to production rendering.
228
+ `,"sdk-docs/catalogs.md":`# Catalogs
229
+
230
+ Catalogs are generated SDK modules that define the allowed components, actions, schemas, docs, examples, and validators for a target UI surface.
231
+
232
+ ## Why catalogs matter
233
+
234
+ A catalog is the source of truth for what an author may use. Humans should read catalog docs for intent and prop semantics. LLMs should inspect catalog metadata before generating code or JSON.
235
+
236
+ A spec should be authored against one catalog at a time. The catalog renderer adds metadata such as:
237
+
238
+ \`\`\`json
239
+ {
240
+ "platform": "web",
241
+ "catalog": "AiChatCatalogV1",
242
+ "catalogVersion": "1.0.0"
243
+ }
244
+ \`\`\`
245
+
246
+ ## Python catalog imports
247
+
248
+ Examples:
249
+
250
+ \`\`\`python
251
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import (
252
+ ConfirmationCard,
253
+ SingleSelectDisambiguation,
254
+ render,
255
+ submit_tool_output,
256
+ validate,
257
+ )
258
+
259
+ from pebble_sdui_mobile.catalogs.MobileGenUICatalogV1 import (
260
+ Button,
261
+ render,
262
+ validate,
263
+ )
264
+ \`\`\`
265
+
266
+ Generated catalog modules export:
267
+
268
+ - component classes and nested prop types
269
+ - event TypedDicts
270
+ - action creators
271
+ - \`CATALOG_NAME\`
272
+ - \`CATALOG_VERSION\`
273
+ - \`get_components()\`
274
+ - \`get_component(name)\`
275
+ - \`get_actions()\`
276
+ - \`get_action(name)\`
277
+ - \`render(root, state=None)\`
278
+ - \`validate(spec)\`
279
+
280
+ ## Component discovery
281
+
282
+ Use \`get_components()\` for a compact list of names and descriptions:
283
+
284
+ \`\`\`python
285
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import get_components
286
+
287
+ for name, description in get_components().items():
288
+ print(name, "-", description)
289
+ \`\`\`
290
+
291
+ Use \`get_component(name)\` before selecting props, events, or children:
292
+
293
+ \`\`\`python
294
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import get_component
295
+
296
+ definition = get_component("AIChat_ConfirmationCard")
297
+ print(definition["description"])
298
+ print(definition["docs"])
299
+ print(definition["events"])
300
+ print(definition["propsSchema"])
301
+ print(definition["acceptsChildren"])
302
+ \`\`\`
303
+
304
+ ## Action discovery
305
+
306
+ Use \`get_actions()\` for a compact action list:
307
+
308
+ \`\`\`python
309
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import get_actions
310
+
311
+ print(get_actions())
312
+ \`\`\`
313
+
314
+ Use \`get_action(name)\` for params and docs:
315
+
316
+ \`\`\`python
317
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import get_action
318
+
319
+ submit = get_action("submitToolOutput")
320
+ print(submit["description"])
321
+ print(submit.get("paramsSchema"))
322
+ \`\`\`
323
+
324
+ ## How humans should use catalogs
325
+
326
+ 1. Start with the catalog for the target surface.
327
+ 2. Use component docstrings and generated types in your editor.
328
+ 3. Read \`get_component()\` when a prop's runtime meaning is unclear.
329
+ 4. Prefer generated action creators over raw dictionaries.
330
+ 5. Validate rendered specs in tests or at service boundaries.
331
+
332
+ ## How LLMs should use catalogs
333
+
334
+ LLMs should treat the catalog as hard constraints:
335
+
336
+ 1. Call or inspect \`get_components()\` to choose candidates.
337
+ 2. Call or inspect \`get_component(name)\` for exact prop names, required props, events, and child support.
338
+ 3. Call or inspect \`get_actions()\` and \`get_action(name)\` for allowed action names and params.
339
+ 4. Generate SDK code using only exported component and action symbols.
340
+ 5. Render the tree.
341
+ 6. Validate and repair any errors.
342
+
343
+ LLMs must not invent:
344
+
345
+ - component names
346
+ - prop names
347
+ - event names
348
+ - action names
349
+ - enum/literal values
350
+ - child support on leaf components
351
+
352
+ ## Choosing a component
353
+
354
+ Prefer the most specific component that matches the user's intent. If two components look similar:
355
+
356
+ - Prefer a component whose description mentions the target workflow.
357
+ - Prefer fewer props over many unused props.
358
+ - Prefer built-in component behavior documented in \`docs\` instead of recreating it with custom state.
359
+ - If the catalog says a component auto-binds or auto-disables behavior, do not duplicate that behavior unless required.
360
+
361
+ ## Catalog upgrades
362
+
363
+ When a catalog version changes:
364
+
365
+ - Re-run validation on representative specs.
366
+ - Check changed component definitions for prop/event differences.
367
+ - For LLM prompt packs, regenerate the catalog excerpt used by the model.
368
+ - Keep examples small so they are easy to update.
369
+ `,"sdk-docs/concepts.md":`# Concepts
370
+
371
+ Pebble Kit authors UI specs for a server-driven UI runtime. Humans and LLMs should use the same mental model: a catalog defines what can be rendered, the SDK builds a component tree, and \`render()\` converts that tree into the runtime wire format.
372
+
373
+ ## Spec
374
+
375
+ A **spec** is the JSON object sent to the renderer. It contains:
376
+
377
+ - \`platform\` — target platform, such as \`web\` or \`mobile\`.
378
+ - \`catalog\` and \`catalogVersion\` — the component/action vocabulary used by the spec.
379
+ - \`root\` — the ID of the root element.
380
+ - \`elements\` — a flat map of element ID to element definition.
381
+ - \`state\` — optional initial state for runtime expressions.
382
+
383
+ SDK authors normally build a tree and let \`render()\` create this flat spec.
384
+
385
+ ## Catalog
386
+
387
+ A **catalog** is a generated module for one UI vocabulary. It contains:
388
+
389
+ - component classes/builders
390
+ - action creators
391
+ - catalog metadata
392
+ - introspection helpers
393
+ - a catalog-scoped \`render()\` function
394
+ - a catalog-scoped \`validate()\` function
395
+
396
+ Catalogs are isolated. Do not mix components from different catalogs in one tree unless the catalog explicitly supports it.
397
+
398
+ ## Component
399
+
400
+ A **component** is a generated class that represents a renderable UI element. Component fields become runtime props. Common element-level fields include:
401
+
402
+ - \`id\` — optional explicit element ID.
403
+ - \`children\` — nested child elements when supported.
404
+ - \`events\` — event handlers keyed by event name.
405
+ - \`visible\` — condition controlling visibility.
406
+ - \`watch_handlers\` — actions triggered by state path changes.
407
+ - \`repeat\` — list repetition binding.
408
+
409
+ ## Action
410
+
411
+ An **action** is an event-side effect. Catalog action creators return opaque \`ActionBinding\` values. Use generated action creators instead of constructing action dictionaries by hand.
412
+
413
+ Actions may accept \`ActionOptions\` for confirmation, success handling, error handling, or \`preventDefault\` where supported.
414
+
415
+ ## State
416
+
417
+ **State** is the runtime data model. Python authors define state shape with annotated classes and initial values with dictionaries. State paths are serialized into expressions such as:
418
+
419
+ \`\`\`json
420
+ { "$state": "/user/name" }
421
+ \`\`\`
422
+
423
+ Use state for values that the runtime can read, bind, compare, or update.
424
+
425
+ ## Binding
426
+
427
+ A **binding** is a two-way reference. It lets an input-like component write back to state:
428
+
429
+ \`\`\`json
430
+ { "$bindState": "/form/email" }
431
+ \`\`\`
432
+
433
+ Use read-only refs for display and comparisons. Use bindings only when the component is expected to update state.
434
+
435
+ ## Expressions
436
+
437
+ Expressions are runtime-resolved values used inside props, visibility, action params, and repeat definitions.
438
+
439
+ Common expression forms:
440
+
441
+ - \`$state\` — read a state path.
442
+ - \`$bindState\` — two-way bind a state path.
443
+ - \`$item\` — read a field from the current repeated item.
444
+ - \`$bindItem\` — two-way bind a repeated item field.
445
+ - \`$index\` — current repeat index.
446
+ - \`$template\` — interpolate state refs into a string.
447
+ - \`$cond\` — choose between two values based on a condition.
448
+
449
+ ## Conditions
450
+
451
+ A **condition** controls visibility or conditional expressions. Conditions can compare refs against literals or other state refs:
452
+
453
+ - equals / not equals
454
+ - greater than / greater than or equal
455
+ - less than / less than or equal
456
+ - truthy / falsy
457
+ - logical \`and_\`, \`or_\`, \`not_\`
458
+
459
+ ## Repeat
460
+
461
+ A **repeat** renders an element once per item in a list state path. It provides:
462
+
463
+ - a repeat binding attached to the repeated component
464
+ - an item accessor for \`$item\`, \`$bindItem\`, and \`$index\`
465
+
466
+ Use repeat for data-driven lists instead of manually creating fixed children when the list length is dynamic.
467
+
468
+ ## Rendering
469
+
470
+ \`render(root, state)\` walks the tree, assigns IDs where needed, serializes props and expressions, and returns the flat spec. Generated catalog renderers also stamp \`platform\`, \`catalog\`, and \`catalogVersion\`.
471
+
472
+ ## Validation
473
+
474
+ \`validate(spec)\` checks a rendered or generated spec against the catalog. Validation returns a list of error strings; an empty list means valid.
475
+
476
+ Use validation especially when:
477
+
478
+ - an LLM created or edited the spec
479
+ - JSON was hand-written
480
+ - a spec crosses service boundaries
481
+ - a component catalog was upgraded
482
+ `,"sdk-docs/validation.md":`# Validation
483
+
484
+ Validation checks a spec against a catalog's component schemas and structural rules. It is required for LLM-authored or hand-authored JSON and recommended for service boundaries.
485
+
486
+ ## API
487
+
488
+ Generated catalog modules export \`validate(spec)\`:
489
+
490
+ \`\`\`python
491
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import validate
492
+
493
+ errors: list[str] = validate(spec)
494
+ if errors:
495
+ raise ValueError("Invalid SDUI spec:\\n" + "\\n".join(errors))
496
+ \`\`\`
497
+
498
+ An empty list means the spec is valid:
499
+
500
+ \`\`\`python
501
+ assert validate(spec) == []
502
+ \`\`\`
503
+
504
+ ## What validation checks
505
+
506
+ Catalog validation checks:
507
+
508
+ - the root ID exists in the \`elements\` map
509
+ - every element \`type\` is known by the catalog
510
+ - element props match the component \`propsSchema\`
511
+ - reactive refs are accepted where literal props are accepted
512
+ - event names are valid for the component
513
+ - leaf components do not receive children
514
+
515
+ Validation does not prove the receiving business action will succeed. It proves the UI spec matches the catalog shape.
516
+
517
+ ## Validate after rendering
518
+
519
+ Humans should usually validate the rendered spec, not the component tree:
520
+
521
+ \`\`\`python
522
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import ConfirmationCard, render, submit_tool_output, validate
523
+
524
+ root = ConfirmationCard(
525
+ question="Proceed?",
526
+ events={"confirm": submit_tool_output(output=True)},
527
+ )
528
+
529
+ spec = render(root)
530
+ errors = validate(spec)
531
+ assert errors == [], errors
532
+ \`\`\`
533
+
534
+ ## Validate generated JSON
535
+
536
+ If an LLM or external service emits raw JSON, validate before rendering it in a client:
537
+
538
+ \`\`\`python
539
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import validate
540
+
541
+ errors = validate(candidate_spec)
542
+ if errors:
543
+ return {"status": "invalid", "validationErrors": errors}
544
+
545
+ return {"status": "valid", "spec": candidate_spec, "validationErrors": []}
546
+ \`\`\`
547
+
548
+ ## Common errors and fixes
549
+
550
+ | Error type | Likely cause | Fix |
551
+ |---|---|---|
552
+ | \`Root element ... not found\` | \`root\` points to a missing ID | Render from the real root or fix the ID |
553
+ | \`unknown type\` | Component name is not in the catalog | Use \`get_components()\` and generated component classes |
554
+ | \`props ... is a required property\` | Required prop omitted | Add the required prop |
555
+ | \`additional properties are not allowed\` | Invented or misspelled prop | Use exact \`propsSchema\` names |
556
+ | \`unknown event\` | Invented or wrong event name | Use events from \`get_component(name)["events"]\` |
557
+ | \`does not accept children\` | Children passed to a leaf component | Remove children or use a container component |
558
+ | Type mismatch | Prop value shape is wrong | Match the JSON Schema type or use a compatible reactive ref |
559
+
560
+ ## LLM repair workflow
561
+
562
+ For AI-generated specs, repair one validation class at a time:
563
+
564
+ 1. Run \`validate(spec)\`.
565
+ 2. Feed all errors back to the LLM.
566
+ 3. Require the LLM to cite the catalog field it used to fix each error.
567
+ 4. Regenerate SDK code or JSON.
568
+ 5. Validate again.
569
+ 6. Stop only when errors are empty.
570
+
571
+ Prompt template:
572
+
573
+ \`\`\`text
574
+ Validation failed for this Pebble Kit spec:
575
+ <errors>
576
+
577
+ Repair rules:
578
+ - Make the smallest change.
579
+ - Use only catalog-backed component, prop, event, and action names.
580
+ - Preserve the user intent.
581
+ - Return updated SDK code and validation status.
582
+ \`\`\`
583
+
584
+ ## Testing pattern
585
+
586
+ Add tests around representative specs:
587
+
588
+ \`\`\`python
589
+ def test_confirmation_card_spec_is_valid() -> None:
590
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import ConfirmationCard, render, submit_tool_output, validate
591
+
592
+ spec = render(
593
+ ConfirmationCard(
594
+ question="Approve?",
595
+ events={"confirm": submit_tool_output(output="approved")},
596
+ )
597
+ )
598
+
599
+ assert validate(spec) == []
600
+ \`\`\`
601
+
602
+ ## Production guidance
603
+
604
+ - Validate specs from LLMs before sending them to clients.
605
+ - Validate during CI for checked-in examples or fixture specs.
606
+ - Log validation errors with catalog name and version.
607
+ - Treat validation failures as authoring bugs, not renderer bugs.
608
+ - Keep validation close to the catalog used to render or consume the spec.
609
+ `,"sdk-docs/typescript/README.md":`# TypeScript SDK
610
+
611
+ The TypeScript SDK lets frontend and backend TypeScript code author type-safe SDUI specs. Platform packages export shared expression helpers, while generated catalog subpaths export components, actions, rendering, introspection, and validation.
612
+
613
+ ## Packages and imports
614
+
615
+ Core authoring helpers come from the platform package:
616
+
617
+ \`\`\`ts
618
+ import { createSpec, equals, truthy, and_ } from '@rippling/pebble-sdui-web';
619
+ \`\`\`
620
+
621
+ Catalog-specific builders come from generated catalog subpaths:
622
+
623
+ \`\`\`ts
624
+ import {
625
+ Button,
626
+ Text,
627
+ VStack,
628
+ render,
629
+ showNotification,
630
+ validate,
631
+ } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
632
+ \`\`\`
633
+
634
+ ## Quick start
635
+
636
+ \`\`\`ts
637
+ import { createSpec, truthy } from '@rippling/pebble-sdui-web';
638
+ import {
639
+ Button,
640
+ Text,
641
+ VStack,
642
+ render,
643
+ showNotification,
644
+ validate,
645
+ } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
646
+
647
+ interface AppState {
648
+ userName: string;
649
+ isReady: boolean;
650
+ }
651
+
652
+ const { $state, $template } = createSpec<AppState>({
653
+ state: {
654
+ userName: 'Alice Nguyen',
655
+ isReady: true,
656
+ },
657
+ });
658
+
659
+ const root = VStack({
660
+ id: 'root',
661
+ props: { gap: 12 },
662
+ visible: truthy($state('isReady')),
663
+ children: [
664
+ Text({
665
+ props: {
666
+ text: $template\`Hello \${$state('userName')}\`,
667
+ },
668
+ }),
669
+ Button({
670
+ props: {
671
+ label: 'Continue',
672
+ appearance: 'PRIMARY',
673
+ },
674
+ on: {
675
+ press: showNotification({
676
+ message: 'Continuing',
677
+ variant: 'success',
678
+ }),
679
+ },
680
+ }),
681
+ ],
682
+ });
683
+
684
+ const spec = render({
685
+ root,
686
+ state: {
687
+ userName: 'Alice Nguyen',
688
+ isReady: true,
689
+ },
690
+ });
691
+
692
+ const errors = validate(spec);
693
+ if (errors.length > 0) {
694
+ throw new Error(\`Invalid spec:\\n\${errors.join('\\n')}\`);
695
+ }
696
+ \`\`\`
697
+
698
+ ## Authoring steps
699
+
700
+ 1. Define a TypeScript state interface.
701
+ 2. Create state helpers with \`createSpec<State>({ state })\`.
702
+ 3. Import components/actions from one generated catalog subpath.
703
+ 4. Compose a component tree with generated builder functions.
704
+ 5. Use \`$state()\`, \`$bindState()\`, \`$template\`, \`$cond()\`, and \`repeat()\` for dynamic behavior.
705
+ 6. Call the catalog \`render({ root, state })\`.
706
+ 7. Call the catalog \`validate(spec)\` for generated, hand-authored, or externally consumed specs.
707
+
708
+ ## Human authoring benefits
709
+
710
+ - Editor autocomplete for component props and event names.
711
+ - TypeScript validates state paths and expression result types.
712
+ - Component builders enforce whether \`children\` and \`on\` are allowed.
713
+ - Action creators enforce action params.
714
+ - Catalog \`render()\` stamps platform/catalog metadata.
715
+
716
+ ## LLM authoring benefits
717
+
718
+ - Catalog introspection gives exact names and schemas.
719
+ - SDK code is easier to validate and repair than raw JSON.
720
+ - Generated builders prevent many invalid tree shapes.
721
+ - Validation errors provide deterministic repair feedback.
722
+
723
+ ## More TypeScript docs
724
+
725
+ - [components-actions-rendering.md](./components-actions-rendering.md)
726
+ - [state-expressions.md](./state-expressions.md)
727
+ `,"sdk-docs/typescript/components-actions-rendering.md":`# TypeScript components, actions, and rendering
728
+
729
+ Generated catalog subpaths provide component builder functions, prop/event types, action creators, introspection helpers, a catalog \`render()\` function, and \`validate()\`.
730
+
731
+ ## Import from one catalog
732
+
733
+ Keep a tree within one generated catalog:
734
+
735
+ \`\`\`ts
736
+ import {
737
+ Button,
738
+ Text,
739
+ VStack,
740
+ render,
741
+ showNotification,
742
+ validate,
743
+ } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
744
+ \`\`\`
745
+
746
+ Do not mix components from different platforms or catalogs in one spec.
747
+
748
+ ## Components
749
+
750
+ Components are generated builder functions. They accept an input object with:
751
+
752
+ - \`id\` — optional explicit element ID.
753
+ - \`props\` — component props.
754
+ - \`visible\` — visibility condition or boolean.
755
+ - \`repeat\` — repeat binding.
756
+ - \`on\` — event handlers, only when the component has events.
757
+ - \`children\` — child elements, only when the component accepts children.
758
+
759
+ \`\`\`ts
760
+ const title = Text({
761
+ id: 'title',
762
+ props: {
763
+ text: 'Welcome',
764
+ typestyle: 'title3',
765
+ },
766
+ });
767
+ \`\`\`
768
+
769
+ Container components accept children when generated with child support:
770
+
771
+ \`\`\`ts
772
+ const root = VStack({
773
+ id: 'root',
774
+ props: { gap: 12 },
775
+ children: [
776
+ Text({ props: { text: 'Welcome' } }),
777
+ Button({ props: { label: 'Continue', appearance: 'PRIMARY' } }),
778
+ ],
779
+ });
780
+ \`\`\`
781
+
782
+ If TypeScript rejects \`children\`, the component is a leaf. Choose a container component or remove the children.
783
+
784
+ ## Props and expression values
785
+
786
+ Generated component props accept either literal values or compatible expressions.
787
+
788
+ \`\`\`ts
789
+ import { createSpec } from '@rippling/pebble-sdui-web';
790
+ import { Text } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
791
+
792
+ interface AppState {
793
+ title: string;
794
+ }
795
+
796
+ const { $state } = createSpec<AppState>({ state: { title: 'Hello' } });
797
+
798
+ const title = Text({
799
+ props: {
800
+ text: $state('title'),
801
+ },
802
+ });
803
+ \`\`\`
804
+
805
+ ## Events
806
+
807
+ Events are component-specific and type checked. For example, \`Button\` supports events such as \`press\`.
808
+
809
+ \`\`\`ts
810
+ const button = Button({
811
+ props: { label: 'Save', appearance: 'PRIMARY' },
812
+ on: {
813
+ press: showNotification({
814
+ message: 'Saved',
815
+ variant: 'success',
816
+ }),
817
+ },
818
+ });
819
+ \`\`\`
820
+
821
+ Use catalog introspection when generating code or when unsure:
822
+
823
+ \`\`\`ts
824
+ import { getComponent } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
825
+
826
+ const definition = getComponent('Button');
827
+ console.log(definition.events);
828
+ console.log(definition.propsSchema);
829
+ \`\`\`
830
+
831
+ ## Actions
832
+
833
+ Action creators are generated from the catalog and return opaque action bindings. Use generated creators instead of manually building action dictionaries.
834
+
835
+ \`\`\`ts
836
+ import { navigate, setState, showNotification } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
837
+
838
+ const notify = showNotification({
839
+ message: 'Saved',
840
+ variant: 'success',
841
+ });
842
+
843
+ const nav = navigate({
844
+ path: '/home',
845
+ openInNewTab: false,
846
+ });
847
+
848
+ const update = setState({
849
+ statePath: 'form.status',
850
+ value: 'submitted',
851
+ });
852
+ \`\`\`
853
+
854
+ Action creators can also take shared action options:
855
+
856
+ \`\`\`ts
857
+ const dangerous = setState(
858
+ { statePath: 'record.deleted', value: true },
859
+ {
860
+ confirm: {
861
+ title: 'Delete record?',
862
+ message: 'This cannot be undone.',
863
+ confirmLabel: 'Delete',
864
+ cancelLabel: 'Cancel',
865
+ variant: 'danger',
866
+ },
867
+ }
868
+ );
869
+ \`\`\`
870
+
871
+ ## Rendering
872
+
873
+ Use the generated catalog \`render()\`:
874
+
875
+ \`\`\`ts
876
+ const spec = render({
877
+ root,
878
+ state: {
879
+ title: 'Welcome',
880
+ },
881
+ });
882
+ \`\`\`
883
+
884
+ The catalog renderer:
885
+
886
+ - flattens the tree into \`elements\`
887
+ - generates IDs for elements without explicit IDs
888
+ - checks duplicate explicit IDs during render
889
+ - serializes props, events, expressions, children, and repeats
890
+ - adds \`platform\`, \`catalog\`, and \`catalogVersion\`
891
+
892
+ Example output shape:
893
+
894
+ \`\`\`json
895
+ {
896
+ "root": "root",
897
+ "elements": {
898
+ "root": {
899
+ "type": "VStack",
900
+ "props": { "gap": 12 },
901
+ "children": ["element-0", "element-1"]
902
+ },
903
+ "element-0": {
904
+ "type": "Text",
905
+ "props": { "text": "Welcome" }
906
+ }
907
+ },
908
+ "state": { "title": "Welcome" },
909
+ "platform": "web",
910
+ "catalog": "custom-apps",
911
+ "catalogVersion": "1.0.0"
912
+ }
913
+ \`\`\`
914
+
915
+ ## Validation
916
+
917
+ Validate after render:
918
+
919
+ \`\`\`ts
920
+ const errors = validate(spec);
921
+ if (errors.length > 0) {
922
+ throw new Error(errors.join('\\n'));
923
+ }
924
+ \`\`\`
925
+
926
+ Use validation in tests, LLM workflows, and service boundaries.
927
+
928
+ ## Introspection
929
+
930
+ Generated catalogs export compact and detailed introspection helpers:
931
+
932
+ \`\`\`ts
933
+ import {
934
+ getActions,
935
+ getAction,
936
+ getComponents,
937
+ getComponent,
938
+ } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
939
+
940
+ console.log(getComponents());
941
+ console.log(getComponent('Button'));
942
+ console.log(getActions());
943
+ console.log(getAction('showNotification'));
944
+ \`\`\`
945
+
946
+ LLMs should call or inspect these helpers before generating SDK code.
947
+
948
+ ## Practical authoring rules
949
+
950
+ - Use generated component builders and action creators.
951
+ - Keep \`props\` explicit and small.
952
+ - Use exact event names from generated types or \`getComponent()\`.
953
+ - Do not pass \`children\` to leaf components.
954
+ - Prefer catalog \`render()\` over core \`createSpec().render()\` for app specs.
955
+ - Validate any spec produced by an LLM or external transformation.
956
+ `,"sdk-docs/typescript/state-expressions.md":`# TypeScript state and expressions
957
+
958
+ State and expressions make TypeScript-authored specs dynamic. The SDK uses typed path strings and phantom-typed expression objects so props and action params can accept runtime values while remaining type checked.
959
+
960
+ ## Define state
961
+
962
+ Define state as a TypeScript interface or type:
963
+
964
+ \`\`\`ts
965
+ interface Todo {
966
+ id: string;
967
+ text: string;
968
+ done: boolean;
969
+ }
970
+
971
+ interface AppState {
972
+ user: {
973
+ name: string;
974
+ role: 'admin' | 'employee';
975
+ };
976
+ todos: Todo[];
977
+ count: number;
978
+ active: boolean;
979
+ }
980
+ \`\`\`
981
+
982
+ Create helpers with \`createSpec\`:
983
+
984
+ \`\`\`ts
985
+ import { createSpec } from '@rippling/pebble-sdui-web';
986
+
987
+ const specContext = createSpec<AppState>({
988
+ state: {
989
+ user: { name: 'Alice', role: 'admin' },
990
+ todos: [{ id: '1', text: 'Review', done: false }],
991
+ count: 1,
992
+ active: true,
993
+ },
994
+ });
995
+
996
+ const { $state, $bindState, $template, $cond, repeat } = specContext;
997
+ \`\`\`
998
+
999
+ ## Read state paths
1000
+
1001
+ Use \`$state(path)\` for read-only runtime refs.
1002
+
1003
+ \`\`\`ts
1004
+ const nameRef = $state('user.name');
1005
+ // Renders as: { "$state": "user.name" }
1006
+ \`\`\`
1007
+
1008
+ The path is type checked against \`AppState\`. Invalid paths should fail TypeScript type checking.
1009
+
1010
+ ## Bind state
1011
+
1012
+ Use \`$bindState(path)\` when a component should write back to state.
1013
+
1014
+ \`\`\`ts
1015
+ const nameBinding = $bindState('user.name');
1016
+ // Renders as: { "$bindState": "user.name" }
1017
+ \`\`\`
1018
+
1019
+ Use bindings only for props documented as writable, such as form values or selected values.
1020
+
1021
+ ## Templates
1022
+
1023
+ \`$template\` is a tagged template helper for string interpolation.
1024
+
1025
+ \`\`\`ts
1026
+ const greeting = $template\`Hello \${$state('user.name')}!\`;
1027
+ // Renders as: { "$template": "Hello \${user.name}!" }
1028
+ \`\`\`
1029
+
1030
+ Template interpolations may include state refs, item refs, indexes, \`null\`, or \`undefined\`.
1031
+
1032
+ ## Conditions
1033
+
1034
+ Conditions are used for \`visible\` and \`$cond()\`.
1035
+
1036
+ \`\`\`ts
1037
+ import { equals, gt, truthy, and_, or_, not_ } from '@rippling/pebble-sdui-web';
1038
+
1039
+ const isAdmin = equals($state('user.role'), 'admin');
1040
+ const hasTodos = gt($state('count'), 0);
1041
+ const show = and_(isAdmin, hasTodos);
1042
+ \`\`\`
1043
+
1044
+ Available condition helpers:
1045
+
1046
+ - \`equals(ref, value)\`
1047
+ - \`neq(ref, value)\`
1048
+ - \`gt(ref, value)\`
1049
+ - \`gte(ref, value)\`
1050
+ - \`lt(ref, value)\`
1051
+ - \`lte(ref, value)\`
1052
+ - \`truthy(ref)\`
1053
+ - \`falsy(ref)\`
1054
+ - \`not_(condition)\`
1055
+ - \`and_(...conditions)\` / \`$and(...conditions)\`
1056
+ - \`or_(...conditions)\` / \`$or(...conditions)\`
1057
+
1058
+ ## Conditional expressions
1059
+
1060
+ Use \`$cond(condition, thenValue, elseValue)\` for runtime prop values.
1061
+
1062
+ \`\`\`ts
1063
+ const statusColor = $cond(
1064
+ equals($state('active'), true),
1065
+ 'green',
1066
+ 'gray'
1067
+ );
1068
+ \`\`\`
1069
+
1070
+ Both branches should resolve to the same prop type.
1071
+
1072
+ ## Repeat over lists
1073
+
1074
+ \`repeat(path, key?)\` creates a repeat binding and a typed item accessor.
1075
+
1076
+ \`\`\`ts
1077
+ const [todoRepeat, todo] = repeat('todos', 'id');
1078
+
1079
+ const textRef = todo.$('text'); // { "$item": "text" }
1080
+ const doneBind = todo.$bind('done'); // { "$bindItem": "done" }
1081
+ const indexRef = todo.$index(); // { "$index": true }
1082
+ \`\`\`
1083
+
1084
+ Attach the repeat binding to the component that should render once per item:
1085
+
1086
+ \`\`\`ts
1087
+ import { Text } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
1088
+
1089
+ const repeatedText = Text({
1090
+ repeat: todoRepeat,
1091
+ props: {
1092
+ text: todo.$('text'),
1093
+ },
1094
+ });
1095
+ \`\`\`
1096
+
1097
+ ## Render helper on \`createSpec\`
1098
+
1099
+ \`createSpec()\` includes a core \`render(root)\` helper, but catalog authors should prefer the generated catalog \`render({ root, state })\` because it stamps platform and catalog metadata.
1100
+
1101
+ Use the core helper only in low-level tests or core-only tooling.
1102
+
1103
+ ## Serialization summary
1104
+
1105
+ | TypeScript helper | Rendered shape | Use |
1106
+ |---|---|---|
1107
+ | \`$state('path')\` | \`{ "$state": "path" }\` | read state |
1108
+ | \`$bindState('path')\` | \`{ "$bindState": "path" }\` | two-way state binding |
1109
+ | \`item.$('field')\` | \`{ "$item": "field" }\` | read repeated item field |
1110
+ | \`item.$bind('field')\` | \`{ "$bindItem": "field" }\` | bind repeated item field |
1111
+ | \`item.$index()\` | \`{ "$index": true }\` | repeat index |
1112
+ | \`$template\\\`...\\\`\` | \`{ "$template": "..." }\` | string interpolation |
1113
+ | \`$cond(...)\` | \`{ "$cond": ..., "$then": ..., "$else": ... }\` | conditional prop value |
1114
+ `};function s(){return o.map(({key:e,filePath:t,title:a})=>({key:e,filePath:t,title:a}))}function r(e){if(!(e in n))throw new Error(`Unknown SDK doc filePath: ${e}`);return n[e]}exports.listSdkDocs=s;exports.readSdkDoc=r;
1115
+ //# sourceMappingURL=sdk-docs.cjs.map