@rippling/pebble-sdui-web 0.2.0 → 0.3.0

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/README.md ADDED
@@ -0,0 +1,118 @@
1
+ # TypeScript SDK
2
+
3
+ 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.
4
+
5
+ ## Packages and imports
6
+
7
+ Core authoring helpers come from the platform package:
8
+
9
+ ```ts
10
+ import { createSpec, equals, truthy, and_ } from '@rippling/pebble-sdui-web';
11
+ ```
12
+
13
+ Catalog-specific builders come from generated catalog subpaths:
14
+
15
+ ```ts
16
+ import {
17
+ Button,
18
+ Text,
19
+ VStack,
20
+ render,
21
+ showNotification,
22
+ validate,
23
+ } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
24
+ ```
25
+
26
+ ## Quick start
27
+
28
+ ```ts
29
+ import { createSpec, truthy } from '@rippling/pebble-sdui-web';
30
+ import {
31
+ Button,
32
+ Text,
33
+ VStack,
34
+ render,
35
+ showNotification,
36
+ validate,
37
+ } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
38
+
39
+ interface AppState {
40
+ userName: string;
41
+ isReady: boolean;
42
+ }
43
+
44
+ const { $state, $template } = createSpec<AppState>({
45
+ state: {
46
+ userName: 'Alice Nguyen',
47
+ isReady: true,
48
+ },
49
+ });
50
+
51
+ const root = VStack({
52
+ id: 'root',
53
+ props: { gap: 12 },
54
+ visible: truthy($state('isReady')),
55
+ children: [
56
+ Text({
57
+ props: {
58
+ text: $template`Hello ${$state('userName')}`,
59
+ },
60
+ }),
61
+ Button({
62
+ props: {
63
+ label: 'Continue',
64
+ appearance: 'PRIMARY',
65
+ },
66
+ on: {
67
+ press: showNotification({
68
+ message: 'Continuing',
69
+ variant: 'success',
70
+ }),
71
+ },
72
+ }),
73
+ ],
74
+ });
75
+
76
+ const spec = render({
77
+ root,
78
+ state: {
79
+ userName: 'Alice Nguyen',
80
+ isReady: true,
81
+ },
82
+ });
83
+
84
+ const errors = validate(spec);
85
+ if (errors.length > 0) {
86
+ throw new Error(`Invalid spec:\n${errors.join('\n')}`);
87
+ }
88
+ ```
89
+
90
+ ## Authoring steps
91
+
92
+ 1. Define a TypeScript state interface.
93
+ 2. Create state helpers with `createSpec<State>({ state })`.
94
+ 3. Import components/actions from one generated catalog subpath.
95
+ 4. Compose a component tree with generated builder functions.
96
+ 5. Use `$state()`, `$bindState()`, `$template`, `$cond()`, and `repeat()` for dynamic behavior.
97
+ 6. Call the catalog `render({ root, state })`.
98
+ 7. Call the catalog `validate(spec)` for generated, hand-authored, or externally consumed specs.
99
+
100
+ ## Human authoring benefits
101
+
102
+ - Editor autocomplete for component props and event names.
103
+ - TypeScript validates state paths and expression result types.
104
+ - Component builders enforce whether `children` and `on` are allowed.
105
+ - Action creators enforce action params.
106
+ - Catalog `render()` stamps platform/catalog metadata.
107
+
108
+ ## LLM authoring benefits
109
+
110
+ - Catalog introspection gives exact names and schemas.
111
+ - SDK code is easier to validate and repair than raw JSON.
112
+ - Generated builders prevent many invalid tree shapes.
113
+ - Validation errors provide deterministic repair feedback.
114
+
115
+ ## More TypeScript docs
116
+
117
+ - [components-actions-rendering.md](./components-actions-rendering.md)
118
+ - [state-expressions.md](./state-expressions.md)
package/dist/README.md ADDED
@@ -0,0 +1,118 @@
1
+ # TypeScript SDK
2
+
3
+ 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.
4
+
5
+ ## Packages and imports
6
+
7
+ Core authoring helpers come from the platform package:
8
+
9
+ ```ts
10
+ import { createSpec, equals, truthy, and_ } from '@rippling/pebble-sdui-web';
11
+ ```
12
+
13
+ Catalog-specific builders come from generated catalog subpaths:
14
+
15
+ ```ts
16
+ import {
17
+ Button,
18
+ Text,
19
+ VStack,
20
+ render,
21
+ showNotification,
22
+ validate,
23
+ } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
24
+ ```
25
+
26
+ ## Quick start
27
+
28
+ ```ts
29
+ import { createSpec, truthy } from '@rippling/pebble-sdui-web';
30
+ import {
31
+ Button,
32
+ Text,
33
+ VStack,
34
+ render,
35
+ showNotification,
36
+ validate,
37
+ } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
38
+
39
+ interface AppState {
40
+ userName: string;
41
+ isReady: boolean;
42
+ }
43
+
44
+ const { $state, $template } = createSpec<AppState>({
45
+ state: {
46
+ userName: 'Alice Nguyen',
47
+ isReady: true,
48
+ },
49
+ });
50
+
51
+ const root = VStack({
52
+ id: 'root',
53
+ props: { gap: 12 },
54
+ visible: truthy($state('isReady')),
55
+ children: [
56
+ Text({
57
+ props: {
58
+ text: $template`Hello ${$state('userName')}`,
59
+ },
60
+ }),
61
+ Button({
62
+ props: {
63
+ label: 'Continue',
64
+ appearance: 'PRIMARY',
65
+ },
66
+ on: {
67
+ press: showNotification({
68
+ message: 'Continuing',
69
+ variant: 'success',
70
+ }),
71
+ },
72
+ }),
73
+ ],
74
+ });
75
+
76
+ const spec = render({
77
+ root,
78
+ state: {
79
+ userName: 'Alice Nguyen',
80
+ isReady: true,
81
+ },
82
+ });
83
+
84
+ const errors = validate(spec);
85
+ if (errors.length > 0) {
86
+ throw new Error(`Invalid spec:\n${errors.join('\n')}`);
87
+ }
88
+ ```
89
+
90
+ ## Authoring steps
91
+
92
+ 1. Define a TypeScript state interface.
93
+ 2. Create state helpers with `createSpec<State>({ state })`.
94
+ 3. Import components/actions from one generated catalog subpath.
95
+ 4. Compose a component tree with generated builder functions.
96
+ 5. Use `$state()`, `$bindState()`, `$template`, `$cond()`, and `repeat()` for dynamic behavior.
97
+ 6. Call the catalog `render({ root, state })`.
98
+ 7. Call the catalog `validate(spec)` for generated, hand-authored, or externally consumed specs.
99
+
100
+ ## Human authoring benefits
101
+
102
+ - Editor autocomplete for component props and event names.
103
+ - TypeScript validates state paths and expression result types.
104
+ - Component builders enforce whether `children` and `on` are allowed.
105
+ - Action creators enforce action params.
106
+ - Catalog `render()` stamps platform/catalog metadata.
107
+
108
+ ## LLM authoring benefits
109
+
110
+ - Catalog introspection gives exact names and schemas.
111
+ - SDK code is easier to validate and repair than raw JSON.
112
+ - Generated builders prevent many invalid tree shapes.
113
+ - Validation errors provide deterministic repair feedback.
114
+
115
+ ## More TypeScript docs
116
+
117
+ - [components-actions-rendering.md](./components-actions-rendering.md)
118
+ - [state-expressions.md](./state-expressions.md)