@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 +118 -0
- package/dist/README.md +118 -0
- package/dist/sdk-docs.cjs +1115 -0
- package/dist/sdk-docs.cjs.map +1 -0
- package/dist/sdk-docs.d.ts +13 -0
- package/dist/sdk-docs.generated.d.ts +3 -0
- package/dist/sdk-docs.js +1181 -0
- package/dist/sdk-docs.js.map +1 -0
- package/package.json +6 -1
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)
|