@niscorp/nova 0.1.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/ACTION_DOCS.md +552 -0
- package/ADAPTER.md +170 -0
- package/DESIGN.md +719 -0
- package/I18N_DOCS.md +224 -0
- package/LAYOUT_DOCS.md +505 -0
- package/LICENSE +202 -0
- package/REACT_DOCS.md +562 -0
- package/README.md +379 -0
- package/SHELL_DOCS.md +615 -0
- package/TERMINAL_DOCS.md +124 -0
- package/dist/adapters/dom/components/index.cjs +473 -0
- package/dist/adapters/dom/components/index.cjs.map +1 -0
- package/dist/adapters/dom/components/index.d.cts +48 -0
- package/dist/adapters/dom/components/index.d.ts +48 -0
- package/dist/adapters/dom/components/index.js +420 -0
- package/dist/adapters/dom/components/index.js.map +1 -0
- package/dist/adapters/dom/index.cjs +171 -0
- package/dist/adapters/dom/index.cjs.map +1 -0
- package/dist/adapters/dom/index.d.cts +29 -0
- package/dist/adapters/dom/index.d.ts +29 -0
- package/dist/adapters/dom/index.js +15 -0
- package/dist/adapters/dom/index.js.map +1 -0
- package/dist/adapters/dom/server.cjs +129 -0
- package/dist/adapters/dom/server.cjs.map +1 -0
- package/dist/adapters/dom/server.d.cts +15 -0
- package/dist/adapters/dom/server.d.ts +15 -0
- package/dist/adapters/dom/server.js +37 -0
- package/dist/adapters/dom/server.js.map +1 -0
- package/dist/adapters/ink/index.d.ts +75 -0
- package/dist/adapters/ink/index.js +472 -0
- package/dist/adapters/ink/index.js.map +1 -0
- package/dist/adapters/react/components/index.cjs +552 -0
- package/dist/adapters/react/components/index.cjs.map +1 -0
- package/dist/adapters/react/components/index.d.cts +30 -0
- package/dist/adapters/react/components/index.d.ts +30 -0
- package/dist/adapters/react/components/index.js +12 -0
- package/dist/adapters/react/components/index.js.map +1 -0
- package/dist/adapters/react/index.cjs +1526 -0
- package/dist/adapters/react/index.cjs.map +1 -0
- package/dist/adapters/react/index.d.cts +149 -0
- package/dist/adapters/react/index.d.ts +149 -0
- package/dist/adapters/react/index.js +12 -0
- package/dist/adapters/react/index.js.map +1 -0
- package/dist/adapters/tty/components/index.cjs +255 -0
- package/dist/adapters/tty/components/index.cjs.map +1 -0
- package/dist/adapters/tty/components/index.d.cts +40 -0
- package/dist/adapters/tty/components/index.d.ts +40 -0
- package/dist/adapters/tty/components/index.js +187 -0
- package/dist/adapters/tty/components/index.js.map +1 -0
- package/dist/adapters/tty/index.cjs +76 -0
- package/dist/adapters/tty/index.cjs.map +1 -0
- package/dist/adapters/tty/index.d.cts +47 -0
- package/dist/adapters/tty/index.d.ts +47 -0
- package/dist/adapters/tty/index.js +76 -0
- package/dist/adapters/tty/index.js.map +1 -0
- package/dist/adapters/vue/components/index.cjs +619 -0
- package/dist/adapters/vue/components/index.cjs.map +1 -0
- package/dist/adapters/vue/components/index.d.cts +224 -0
- package/dist/adapters/vue/components/index.d.ts +224 -0
- package/dist/adapters/vue/components/index.js +12 -0
- package/dist/adapters/vue/components/index.js.map +1 -0
- package/dist/adapters/vue/index.cjs +747 -0
- package/dist/adapters/vue/index.cjs.map +1 -0
- package/dist/adapters/vue/index.d.cts +98 -0
- package/dist/adapters/vue/index.d.ts +98 -0
- package/dist/adapters/vue/index.js +127 -0
- package/dist/adapters/vue/index.js.map +1 -0
- package/dist/agent/index.cjs +178 -0
- package/dist/agent/index.cjs.map +1 -0
- package/dist/agent/index.d.cts +28 -0
- package/dist/agent/index.d.ts +28 -0
- package/dist/agent/index.js +30 -0
- package/dist/agent/index.js.map +1 -0
- package/dist/chunk-2MNLEL45.js +47 -0
- package/dist/chunk-2MNLEL45.js.map +1 -0
- package/dist/chunk-3HGE3VWK.js +753 -0
- package/dist/chunk-3HGE3VWK.js.map +1 -0
- package/dist/chunk-4ZID7UX5.js +549 -0
- package/dist/chunk-4ZID7UX5.js.map +1 -0
- package/dist/chunk-7B3RDENH.js +1982 -0
- package/dist/chunk-7B3RDENH.js.map +1 -0
- package/dist/chunk-7S5BNPUS.js +54 -0
- package/dist/chunk-7S5BNPUS.js.map +1 -0
- package/dist/chunk-7TS3YVQR.js +114 -0
- package/dist/chunk-7TS3YVQR.js.map +1 -0
- package/dist/chunk-EG2RUXJN.js +266 -0
- package/dist/chunk-EG2RUXJN.js.map +1 -0
- package/dist/chunk-GVBBL36G.js +429 -0
- package/dist/chunk-GVBBL36G.js.map +1 -0
- package/dist/chunk-I5D2R5UA.js +753 -0
- package/dist/chunk-I5D2R5UA.js.map +1 -0
- package/dist/chunk-IGLCWXQ3.js +304 -0
- package/dist/chunk-IGLCWXQ3.js.map +1 -0
- package/dist/chunk-JI7ZRESP.js +64 -0
- package/dist/chunk-JI7ZRESP.js.map +1 -0
- package/dist/chunk-L5223LLX.js +31 -0
- package/dist/chunk-L5223LLX.js.map +1 -0
- package/dist/chunk-LA3BSEMX.js +1905 -0
- package/dist/chunk-LA3BSEMX.js.map +1 -0
- package/dist/chunk-OAMC6R6E.js +121 -0
- package/dist/chunk-OAMC6R6E.js.map +1 -0
- package/dist/chunk-OGD5CCMZ.js +62 -0
- package/dist/chunk-OGD5CCMZ.js.map +1 -0
- package/dist/chunk-PF4OJTYU.js +199 -0
- package/dist/chunk-PF4OJTYU.js.map +1 -0
- package/dist/chunk-PZ5AY32C.js +9 -0
- package/dist/chunk-PZ5AY32C.js.map +1 -0
- package/dist/chunk-RBU5PHN4.js +8 -0
- package/dist/chunk-RBU5PHN4.js.map +1 -0
- package/dist/chunk-RQB4PRPV.js +285 -0
- package/dist/chunk-RQB4PRPV.js.map +1 -0
- package/dist/chunk-V32EVEVM.js +464 -0
- package/dist/chunk-V32EVEVM.js.map +1 -0
- package/dist/chunk-ZITHBBF3.js +85 -0
- package/dist/chunk-ZITHBBF3.js.map +1 -0
- package/dist/devtools/index.cjs +1088 -0
- package/dist/devtools/index.cjs.map +1 -0
- package/dist/devtools/index.d.cts +33 -0
- package/dist/devtools/index.d.ts +33 -0
- package/dist/devtools/index.js +399 -0
- package/dist/devtools/index.js.map +1 -0
- package/dist/effects-CndX9K7D.d.cts +123 -0
- package/dist/effects-CndX9K7D.d.ts +123 -0
- package/dist/endpoints-CD-6Jl-H.d.ts +36 -0
- package/dist/endpoints-Dem-EdRx.d.cts +36 -0
- package/dist/i18n/index.cjs +299 -0
- package/dist/i18n/index.cjs.map +1 -0
- package/dist/i18n/index.d.cts +28 -0
- package/dist/i18n/index.d.ts +28 -0
- package/dist/i18n/index.js +180 -0
- package/dist/i18n/index.js.map +1 -0
- package/dist/index-CNfzSBe2.d.ts +93 -0
- package/dist/index-caZoXSwr.d.cts +93 -0
- package/dist/index.cjs +3723 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +144 -0
- package/dist/index.d.ts +144 -0
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -0
- package/dist/migrations/index.cjs +635 -0
- package/dist/migrations/index.cjs.map +1 -0
- package/dist/migrations/index.d.cts +97 -0
- package/dist/migrations/index.d.ts +97 -0
- package/dist/migrations/index.js +50 -0
- package/dist/migrations/index.js.map +1 -0
- package/dist/palette-CP0wd3bE.d.ts +15 -0
- package/dist/palette-lm0bU9i5.d.cts +15 -0
- package/dist/primitive-props-BH_EJWIe.d.cts +100 -0
- package/dist/primitive-props-BH_EJWIe.d.ts +100 -0
- package/dist/primitive-props-CGoJvmcH.d.cts +100 -0
- package/dist/primitive-props-CGoJvmcH.d.ts +100 -0
- package/dist/reflect/index.cjs +998 -0
- package/dist/reflect/index.cjs.map +1 -0
- package/dist/reflect/index.d.cts +125 -0
- package/dist/reflect/index.d.ts +125 -0
- package/dist/reflect/index.js +13 -0
- package/dist/reflect/index.js.map +1 -0
- package/dist/schemas-DPdeFlCT.d.cts +38 -0
- package/dist/schemas-DPdeFlCT.d.ts +38 -0
- package/dist/schemas-pMyyuXV7.d.cts +47 -0
- package/dist/schemas-pMyyuXV7.d.ts +47 -0
- package/dist/types-Boh9ckdG.d.ts +194 -0
- package/dist/types-Brc7v_pS.d.ts +198 -0
- package/dist/types-ByNSwtUV.d.cts +20 -0
- package/dist/types-DdltMfw7.d.ts +20 -0
- package/dist/types-De0KpxfI.d.cts +198 -0
- package/dist/types-DhHL0twe.d.ts +20 -0
- package/dist/types-Dv6JLmgo.d.cts +194 -0
- package/dist/types-Q80YtOQt.d.cts +20 -0
- package/package.json +237 -0
package/ACTION_DOCS.md
ADDED
|
@@ -0,0 +1,552 @@
|
|
|
1
|
+
# Action — Author Guide
|
|
2
|
+
|
|
3
|
+
How to write nova actions. An action is a stateful unit: it owns a data store, runs lifecycle hooks, listens for events and messages, mutates its data, calls endpoints, and produces a layout that reads from its data. The shell drives instances of actions on canvases (see `SHELL_DOCS.md`).
|
|
4
|
+
|
|
5
|
+
This guide is for **authoring** actions. For the architecture see `DESIGN.md`.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## A first action
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import type { ActionDefinition } from '@niscorp/nova';
|
|
13
|
+
|
|
14
|
+
const counter: ActionDefinition = {
|
|
15
|
+
id: 'counter',
|
|
16
|
+
data: { count: 0 },
|
|
17
|
+
layout: {
|
|
18
|
+
component: 'Stack',
|
|
19
|
+
props: { direction: 'column', gap: 16, padding: 24 },
|
|
20
|
+
children: [
|
|
21
|
+
{ component: 'Text', props: { size: 'xl', weight: 'bold' }, children: 'Count: {{$.count}}' },
|
|
22
|
+
{ component: 'Stack', props: { direction: 'row', gap: 8 }, children: [
|
|
23
|
+
{ component: 'Button', ref: 'inc', children: 'Increment' },
|
|
24
|
+
{ component: 'Button', ref: 'dec', children: 'Decrement' },
|
|
25
|
+
]},
|
|
26
|
+
],
|
|
27
|
+
},
|
|
28
|
+
triggers: [
|
|
29
|
+
{ event: 'ui:click', ref: 'inc', do: [{ increment: 'count' }] },
|
|
30
|
+
{ event: 'ui:click', ref: 'dec', do: [{ decrement: 'count' }] },
|
|
31
|
+
],
|
|
32
|
+
};
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
This is a complete action definition. Pass it to a shell, push it onto a canvas, it runs.
|
|
36
|
+
|
|
37
|
+
## What's in an `ActionDefinition`
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
{
|
|
41
|
+
id: string; // required — stable identifier
|
|
42
|
+
name?: string; // human label (optional)
|
|
43
|
+
description?: string; // free-form description
|
|
44
|
+
title?: string; // resolvable instance label (e.g. '{{$.record.name}}'),
|
|
45
|
+
// exposed as instance.title for stack-nav chrome
|
|
46
|
+
layout?: LayoutNode | string; // inline layout, or an id in the layout store
|
|
47
|
+
data?: Record<string, unknown>; // initial data merged with input on mount
|
|
48
|
+
input?: Record<string, unknown>; // JSON Schema of the data keys an opener may seed —
|
|
49
|
+
// the openable-input contract (descriptive, not enforced)
|
|
50
|
+
triggers?: TriggerConfig[]; // event/message → step bindings
|
|
51
|
+
endpoints?: Record<string, EndpointConfig>; // named HTTP or local-function calls
|
|
52
|
+
lifecycle?: LifecycleConfig; // mount/unmount/suspend/resume hooks
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
That's the entire surface. Everything else is composed from these fields.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Data
|
|
61
|
+
|
|
62
|
+
The action's data is a plain object merged from `data` (defaults) + the `input` passed when the action is pushed onto a canvas. It's the **single source of truth** the layout reads from via bindings.
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
data: {
|
|
66
|
+
count: 0,
|
|
67
|
+
user: { name: '', email: '' },
|
|
68
|
+
items: [],
|
|
69
|
+
loading: false,
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Bindings in the layout (`{{$.count}}`, `$.user.name`, etc.) resolve against this object. When mutations or `setData` change it, subscribers (the React adapter's `useRenderTree`, the inspector tabs, etc.) re-render automatically.
|
|
74
|
+
|
|
75
|
+
The data is **immutable from the outside** — every mutation produces a new top-level reference. Internally the store does structural sharing so unchanged subtrees keep their identity.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Triggers
|
|
80
|
+
|
|
81
|
+
A trigger binds an event source to an ordered list of steps. When the event fires, the steps execute in sequence.
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
triggers: [
|
|
85
|
+
// UI click on a component with ref="save"
|
|
86
|
+
{ event: 'ui:click', ref: 'save', do: [...] },
|
|
87
|
+
|
|
88
|
+
// UI input change on a component with ref="email-field"
|
|
89
|
+
{ event: 'ui:input', ref: 'email-field', do: [...] },
|
|
90
|
+
|
|
91
|
+
// Two-way model binding update
|
|
92
|
+
{ event: 'ui:model', ref: 'name-input', do: [...] },
|
|
93
|
+
|
|
94
|
+
// Cross-action message bus subscription
|
|
95
|
+
{ message: 'cart-updated', do: [...] },
|
|
96
|
+
],
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Trigger fields
|
|
100
|
+
|
|
101
|
+
- **`event`** *(optional)* — UI event type. Common values: `ui:click`, `ui:input`, `ui:submit`, `ui:focus`, `ui:blur`, `ui:model`. Custom event names work too.
|
|
102
|
+
- **`message`** *(optional)* — message bus channel name. Listens via the shell's shared message bus, so this trigger fires from emits in any other action on any other canvas.
|
|
103
|
+
- **`ref`** *(optional)* — filter UI events by component ref. If unset, the trigger fires on every event of that type. Has no effect on message triggers.
|
|
104
|
+
- **`do`** *(required)* — ordered array of steps to run.
|
|
105
|
+
|
|
106
|
+
A trigger MUST have either `event` or `message`. Setting both is an error.
|
|
107
|
+
|
|
108
|
+
### When triggers fire
|
|
109
|
+
|
|
110
|
+
Triggers attach when the action mounts and detach when it unmounts. While the action is **suspended** (another action is pushed on top), triggers stay attached but do **not** fire — a suspended action reacts to nothing until it resumes, and the runtime's abort signal prevents in-flight async work from completing. On resume the `mount` hook re-runs (see [Lifecycle hooks](#lifecycle-hooks)), so the action refreshes its own data instead of reacting while backgrounded.
|
|
111
|
+
|
|
112
|
+
A `ui:model` trigger observes the value the event wrote: the runtime applies a `ui:model` to its own model bindings **before** it dispatches the event to triggers, so a trigger's steps read the just-typed value, not the one the field held before the keystroke.
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Steps
|
|
117
|
+
|
|
118
|
+
A step is either a **mutation** (sync, modifies the data store) or an **effect** (may be async, touches the outside world). Steps in a trigger's `do` array execute in order; mutations are applied as a batch when an effect or the end of the list is reached.
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
do: [
|
|
122
|
+
{ set: 'loading', value: true }, // mutation
|
|
123
|
+
{ call: 'fetchUser', onSuccess: [ // effect — the response lands at the endpoint's `target`
|
|
124
|
+
{ set: 'loading', value: false }, // mutation
|
|
125
|
+
]},
|
|
126
|
+
],
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Mutations and effects share the same `do` slot — they're a discriminated union called `Step`.
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## Mutations
|
|
134
|
+
|
|
135
|
+
Mutations are pure, sync operations that produce a new data store from the old one. There are 10 mutation kinds: `set`, `toggle`, `increment`, `decrement`, `push`, `pop`, `removeAt`, `move`, `clear`, `reset`.
|
|
136
|
+
|
|
137
|
+
### `set`
|
|
138
|
+
|
|
139
|
+
Set a path to a literal value or copy from another path.
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
{ set: 'count', value: 0 } // literal
|
|
143
|
+
{ set: 'user.name', value: 'Ada' } // nested path
|
|
144
|
+
{ set: 'previous', from: 'current' } // copy from another path
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### `toggle`
|
|
148
|
+
|
|
149
|
+
Flip a boolean.
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
{ toggle: 'isOpen' }
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
If the field doesn't exist or isn't a boolean, it becomes `true` on first toggle.
|
|
156
|
+
|
|
157
|
+
### `increment` / `decrement`
|
|
158
|
+
|
|
159
|
+
Add or subtract from a number.
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
{ increment: 'count' } // +1
|
|
163
|
+
{ increment: 'count', by: 5 } // +5
|
|
164
|
+
{ decrement: 'count', by: 2 } // -2
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
If the field isn't a number, it's treated as 0.
|
|
168
|
+
|
|
169
|
+
### `push` / `pop`
|
|
170
|
+
|
|
171
|
+
Append to or remove from the end of an array. **Note:** `push` / `pop` here are **mutations** that take a path string. The navigation `push`/`pop` effects (which take an object) live under [Effects](#effects).
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
{ push: 'items', value: { name: 'New item' } }
|
|
175
|
+
{ pop: 'items' }
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### `removeAt`
|
|
179
|
+
|
|
180
|
+
Remove an element at a specific index.
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
{ removeAt: 'items', index: 0 } // remove first
|
|
184
|
+
{ removeAt: 'items', index: 2 } // remove third
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
The index can also be a template string (e.g. `"{{@event.payload}}"`) resolved before applying.
|
|
188
|
+
|
|
189
|
+
### `move`
|
|
190
|
+
|
|
191
|
+
Reorder an array element from one index to another.
|
|
192
|
+
|
|
193
|
+
```ts
|
|
194
|
+
{ move: 'items', from: 0, to: 2 }
|
|
195
|
+
{ move: 'items', from: '{{@event.payload}}', to: 0 }
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
`from` / `to` accept a number or a template string resolved before applying. An out-of-range `from` is a no-op; `to` is clamped into range.
|
|
199
|
+
|
|
200
|
+
### `clear`
|
|
201
|
+
|
|
202
|
+
Empty an array or object, or set a primitive to its zero value.
|
|
203
|
+
|
|
204
|
+
```ts
|
|
205
|
+
{ clear: 'items' } // → []
|
|
206
|
+
{ clear: 'user' } // → {}
|
|
207
|
+
{ clear: 'count' } // → 0
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### `reset`
|
|
211
|
+
|
|
212
|
+
Reset the entire data store to the action's `data` defaults.
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
{ reset: true }
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Use this in a "Cancel" or "Start over" handler.
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## Effects
|
|
223
|
+
|
|
224
|
+
Effects can be async and may reach outside the action's data store. There are ten: `call`, `emit`, `reload`, and the navigation effects `push`, `pop`, `replace`, `popTo`, `resetTo`, `removeInstance`, `removeSelf`.
|
|
225
|
+
|
|
226
|
+
### `call`
|
|
227
|
+
|
|
228
|
+
Invoke a named endpoint. Optional `onSuccess` and `onError` step branches run after the response.
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
{
|
|
232
|
+
call: 'fetchUser',
|
|
233
|
+
onSuccess: [
|
|
234
|
+
{ set: 'loading', value: false },
|
|
235
|
+
{ set: 'user', from: 'fetchUserResponse' },
|
|
236
|
+
],
|
|
237
|
+
onError: [
|
|
238
|
+
{ set: 'loading', value: false },
|
|
239
|
+
{ set: 'errorMessage', value: '{{@error.message}}' },
|
|
240
|
+
],
|
|
241
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
The `onError` branch has access to a special **`@error`** scope inside templates: `{{@error.message}}`, `{{@error.status}}`, `{{@error.data}}`. Use it to surface error messages in the UI.
|
|
245
|
+
|
|
246
|
+
If the endpoint name doesn't exist in the action's `endpoints`, the call fails with a synthetic error and `onError` fires.
|
|
247
|
+
|
|
248
|
+
### `emit`
|
|
249
|
+
|
|
250
|
+
Publish a message on the shell's shared message bus. Other actions (on any canvas) with a matching `message:` trigger receive it.
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
{ emit: { channel: 'cart-updated' } }
|
|
254
|
+
{ emit: { channel: 'user-saved', payload: { id: '{{$.user.id}}' } } }
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
The `payload` is resolved against the current data — templates and bindings work.
|
|
258
|
+
|
|
259
|
+
### `push`, `pop`, `replace`
|
|
260
|
+
|
|
261
|
+
Navigation effects. They escape from the action via the shell's `onNavigate` callback and become canvas operations.
|
|
262
|
+
|
|
263
|
+
```ts
|
|
264
|
+
{ push: { action: 'edit-user' } } // push onto current canvas
|
|
265
|
+
{ push: { action: 'login', canvas: 'modal' } } // push onto a different canvas
|
|
266
|
+
{ push: { action: 'edit-user', input: { id: 'u_42' } } } // with initial data
|
|
267
|
+
{ push: { action: 'edit-user', with: ['modal-frame'] } } // composed with fragments
|
|
268
|
+
|
|
269
|
+
{ pop: true } // pop the current action
|
|
270
|
+
|
|
271
|
+
{ replace: { action: 'step2' } } // replace current with another
|
|
272
|
+
{ replace: { action: 'article-a', canvas: 'content' } } // on a different canvas
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
The `pop` effect uses `pop: true` (a literal boolean) to distinguish it from the `pop` mutation (which takes a string path).
|
|
276
|
+
|
|
277
|
+
`push`, `replace`, and `resetTo` accept an optional `with: [...]` — ids of `ActionFragment`s composed into the action before it is instantiated. Each fragment wraps the action (the action's layout fills the fragment's `{ slot: 'body' }`) and contributes its triggers/data; the action wins on conflict.
|
|
278
|
+
|
|
279
|
+
`input` values resolve against the current data plus the firing event, so a trigger can pass dynamic data to the action it opens — e.g. `input: { record: '@event.payload' }` or `input: { id: '@event.payload.todo_id' }`.
|
|
280
|
+
|
|
281
|
+
### `popTo`, `resetTo`
|
|
282
|
+
|
|
283
|
+
Stack-navigation effects.
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
{ popTo: { instance: 'act-3' } } // pop until this instance is on top
|
|
287
|
+
{ popTo: { canvas: 'main', instance: 'act-3' } }
|
|
288
|
+
|
|
289
|
+
{ resetTo: { action: 'home' } } // clear the canvas, push a new root
|
|
290
|
+
{ resetTo: { action: 'home', canvas: 'main', input: {...}, with: [...] } }
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
`popTo` unmounts everything above the given instance (a no-op if it isn't in the stack) — what a breadcrumb fires. `resetTo` clears the whole stack and pushes one new root — what a screen-level nav fires so drilling into a record doesn't leave a stale stack beneath the new screen.
|
|
294
|
+
|
|
295
|
+
### `reload`
|
|
296
|
+
|
|
297
|
+
```ts
|
|
298
|
+
{ reload: true } // re-run THIS instance's mount hook
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Re-reads the firing instance in place: same instance, same data object, no navigation. It re-runs whatever the action does on `mount`, which is the only definition of "current" the action itself has — a caller never names endpoints.
|
|
302
|
+
|
|
303
|
+
It exists for `mode: 'list'` canvases. A stack canvas suspends what it covers and `resume` already re-runs `mount`, so a revealed action is never stale; a list suspends nothing, so a card mounted once and opened much later would answer with the data it loaded then. `{ reload: true }` is what "opening it" means there. Harmless on an action with no `mount` hook.
|
|
304
|
+
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## Endpoints
|
|
308
|
+
|
|
309
|
+
An endpoint is either a named HTTP call or a named local function call (`EndpointConfigSchema` is the union of the two). Define them once in the action, invoke them via `{call: 'name'}` from any trigger.
|
|
310
|
+
|
|
311
|
+
```ts
|
|
312
|
+
endpoints: {
|
|
313
|
+
fetchUser: {
|
|
314
|
+
url: '/api/users/{{$.userId}}',
|
|
315
|
+
method: 'GET',
|
|
316
|
+
target: 'user',
|
|
317
|
+
},
|
|
318
|
+
saveUser: {
|
|
319
|
+
url: '/api/users/{{$.user.id}}',
|
|
320
|
+
method: 'POST',
|
|
321
|
+
headers: {
|
|
322
|
+
'content-type': 'application/json',
|
|
323
|
+
'authorization': 'Bearer {{$.token}}',
|
|
324
|
+
},
|
|
325
|
+
request: { name: { $ref: '$.user.name' }, email: { $ref: '$.user.email' } },
|
|
326
|
+
target: 'savedUser',
|
|
327
|
+
errorTarget: 'lastError',
|
|
328
|
+
},
|
|
329
|
+
}
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
### HTTP endpoint fields
|
|
333
|
+
|
|
334
|
+
- **`url`** *(required)* — template URL. Bindings work.
|
|
335
|
+
- **`method`** *(required)* — `GET` | `POST` | `PUT` | `PATCH` | `DELETE`.
|
|
336
|
+
- **`headers`** *(optional)* — object of header name → value. Values can be templated; names cannot.
|
|
337
|
+
- **`request`** *(optional)* — a transform config run by the **injected evaluator** (see below) over the action data to build the request body. Static parts are literal; dynamic parts use the evaluator's ops. A string result is sent as-is; anything else is JSON-stringified. Declaring `request` without an injected transform is a hard error — never a silent empty body.
|
|
338
|
+
- **`response`** *(optional)* — a transform config run by the injected evaluator over the reply **exactly as received** (`$` is the reply — object, array, or scalar; no wrapping) to produce the value stored at `target`. Declaring it without an injected transform is a hard error — never the unshaped reply.
|
|
339
|
+
- **`target`** *(optional)* — data path to write the (possibly transformed) response into on success. If unset, the response is discarded.
|
|
340
|
+
- **`errorTarget`** *(optional)* — data path to write the error info into on failure.
|
|
341
|
+
|
|
342
|
+
The evaluator is dependency-injected: `ShellConfig.transform` is a `(config, source) => unknown` function nova never interprets — the host wires in Prism's `evaluate` (or anything else). Initial data is never transformed.
|
|
343
|
+
|
|
344
|
+
### Function endpoints
|
|
345
|
+
|
|
346
|
+
The other side of the union: a call to a host-registered function instead of a URL.
|
|
347
|
+
|
|
348
|
+
```ts
|
|
349
|
+
endpoints: {
|
|
350
|
+
exportCsv: { fn: 'exportCsv', target: 'exportResult' },
|
|
351
|
+
}
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
- **`fn`** *(required)* — key of a function registered in `ShellConfig.functions`. The handler receives `(data, signal)` and its return value is stored at `target`. An unregistered name fails the call.
|
|
355
|
+
- **`target`** / **`errorTarget`** — as above.
|
|
356
|
+
|
|
357
|
+
### The fetch implementation
|
|
358
|
+
|
|
359
|
+
The runtime needs a fetch implementation injected. The shell takes a `fetch?: FetchFn` config option. Default is the global `fetch` if available; otherwise endpoint calls fail.
|
|
360
|
+
|
|
361
|
+
For tests and the showroom, you inject a mock:
|
|
362
|
+
|
|
363
|
+
```ts
|
|
364
|
+
const mockFetch: FetchFn = async (url) => ({
|
|
365
|
+
ok: true,
|
|
366
|
+
status: 200,
|
|
367
|
+
json: async () => ({ name: 'Ada Lovelace' }),
|
|
368
|
+
text: async () => '{"name":"Ada Lovelace"}',
|
|
369
|
+
});
|
|
370
|
+
|
|
371
|
+
createShell({ ..., fetch: mockFetch });
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
---
|
|
375
|
+
|
|
376
|
+
## Lifecycle hooks
|
|
377
|
+
|
|
378
|
+
Run steps when the action transitions through its lifecycle states. Four hooks: `mount`, `unmount`, `suspend`, `resume`.
|
|
379
|
+
|
|
380
|
+
```ts
|
|
381
|
+
lifecycle: {
|
|
382
|
+
mount: [
|
|
383
|
+
{ call: 'fetchUser', onSuccess: [{ set: 'loading', value: false }] },
|
|
384
|
+
],
|
|
385
|
+
unmount: [
|
|
386
|
+
{ call: 'savePartialState' },
|
|
387
|
+
],
|
|
388
|
+
suspend: [
|
|
389
|
+
{ set: 'wasSuspended', value: true },
|
|
390
|
+
],
|
|
391
|
+
resume: [
|
|
392
|
+
{ set: 'wasSuspended', value: false },
|
|
393
|
+
],
|
|
394
|
+
}
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
### When each fires
|
|
398
|
+
|
|
399
|
+
- **`mount`** — when the action is pushed onto a canvas (after `data` and `input` are merged, before triggers attach), and **again on every resume**, before the `resume` hook. A suspended action ignores everything while backgrounded, so re-running `mount` is what brings its data current when it is revealed again.
|
|
400
|
+
- **`suspend`** — when another action is pushed on top, this action transitions from `active` → `suspended`. Triggers stay attached but do not fire while suspended.
|
|
401
|
+
- **`resume`** — when the action above is popped, this action transitions from `suspended` → `active`. Runs after the re-run of `mount`.
|
|
402
|
+
- **`unmount`** — once, when the action is popped from the canvas (or the shell is disposed). Triggers detach AFTER the unmount steps run.
|
|
403
|
+
|
|
404
|
+
In **strict mode** (set `strict: true` on the shell), a failure inside a lifecycle hook surfaces on the next shell call as a `LifecycleError`. In **lax mode** (the default), it routes to the shell's `onError` telemetry and the lifecycle continues.
|
|
405
|
+
|
|
406
|
+
---
|
|
407
|
+
|
|
408
|
+
## The bindings inside steps
|
|
409
|
+
|
|
410
|
+
Step values can use bindings — same syntax as layout bindings.
|
|
411
|
+
|
|
412
|
+
```ts
|
|
413
|
+
// Set with a literal
|
|
414
|
+
{ set: 'count', value: 0 }
|
|
415
|
+
|
|
416
|
+
// Set from another path (copy)
|
|
417
|
+
{ set: 'previous', from: 'current' }
|
|
418
|
+
|
|
419
|
+
// Increment by a value from data
|
|
420
|
+
{ increment: 'total', by: '{{$.delta}}' } // Wait — `by` is typed as number; templates here would need
|
|
421
|
+
// the bare `{{ expr }}` form to preserve the number type.
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
Endpoint URL templates, body templates, header templates all resolve against the current data. The `@error` scope is available inside `onError` chains.
|
|
425
|
+
|
|
426
|
+
---
|
|
427
|
+
|
|
428
|
+
## The `@error` scope
|
|
429
|
+
|
|
430
|
+
When an endpoint call fails and the `onError` chain runs, the error is in scope as `@error`. Reference it via templates:
|
|
431
|
+
|
|
432
|
+
```ts
|
|
433
|
+
onError: [
|
|
434
|
+
{ set: 'errorMessage', value: '{{@error.message}}' },
|
|
435
|
+
{ set: 'errorStatus', value: '{{@error.status}}' },
|
|
436
|
+
],
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
Fields available on `@error`:
|
|
440
|
+
- `message: string`
|
|
441
|
+
- `status: number` (HTTP status, or 0 for network/function errors)
|
|
442
|
+
- `data: unknown` (the response body if any)
|
|
443
|
+
- `aborted?: boolean` (true if the call was aborted by an unmount)
|
|
444
|
+
|
|
445
|
+
---
|
|
446
|
+
|
|
447
|
+
## Action runtime methods
|
|
448
|
+
|
|
449
|
+
When you call `shell.getRuntime(instanceId)` you get a `PublicActionRuntime`:
|
|
450
|
+
|
|
451
|
+
```ts
|
|
452
|
+
type PublicActionRuntime = {
|
|
453
|
+
readonly instance: ActionInstance;
|
|
454
|
+
readonly definition: ActionDefinition;
|
|
455
|
+
getData: () => Record<string, unknown>;
|
|
456
|
+
setData: (next: Record<string, unknown>) => void;
|
|
457
|
+
render: () => RenderNode[];
|
|
458
|
+
onDataChange: (handler: DataChangeHandler) => Unsubscribe;
|
|
459
|
+
onStatusChange: (handler: StatusChangeHandler) => Unsubscribe;
|
|
460
|
+
};
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
- **`getData`** — synchronous snapshot of the data store.
|
|
464
|
+
- **`setData`** — replace the entire data store with a new object. Use for tooling/debugging (the showroom's editable Data tab uses this). Normal mutations should go through triggers.
|
|
465
|
+
- **`render`** — produce the current `RenderNode[]` tree.
|
|
466
|
+
- **`onDataChange`** — subscribe to data changes. Returns an unsubscribe.
|
|
467
|
+
- **`onStatusChange`** — subscribe to status changes (`active`/`suspended`/`unmounted`). Returns an unsubscribe.
|
|
468
|
+
|
|
469
|
+
You don't construct runtimes directly — the shell does that. You access them via `shell.getRuntime(instanceId)`.
|
|
470
|
+
|
|
471
|
+
---
|
|
472
|
+
|
|
473
|
+
## Errors
|
|
474
|
+
|
|
475
|
+
Action-time errors all extend `NovaError`:
|
|
476
|
+
|
|
477
|
+
- **`LifecycleError`** — a step inside a lifecycle hook failed
|
|
478
|
+
- **`UnknownActionError`** — `shell.push(canvas, 'name')` where `'name'` isn't in `actions`
|
|
479
|
+
- **`DefinitionValidationError`** — an action definition fails Zod validation at shell init
|
|
480
|
+
|
|
481
|
+
In strict mode all of these throw. In lax mode they route through the shell's `onError` callback.
|
|
482
|
+
|
|
483
|
+
---
|
|
484
|
+
|
|
485
|
+
## Validation
|
|
486
|
+
|
|
487
|
+
Action definitions are validated against `ActionDefinitionSchema` when you pass them to `createShell`. Invalid definitions throw `DefinitionValidationError` with structured failures listing every Zod issue. So you cannot accidentally run an action with a malformed shape.
|
|
488
|
+
|
|
489
|
+
### `auditAction` — static wiring audit
|
|
490
|
+
|
|
491
|
+
A definition can parse, mount, and render politely while being broken at click time. `auditAction(def, { catalog? })` cross-references the definition against itself: layout bindings ↔ `data` defaults, layout refs ↔ triggers (dead chrome and phantom triggers both), `call` steps ↔ endpoint names, endpoint targets ↔ `data`, mutation paths ↔ `data`, and — when a `catalog` of `{ id, input }` entries is given — push/replace/resetTo targets and their seeded input keys. Returns `{ ok, issues: string[] }` with precise messages.
|
|
492
|
+
|
|
493
|
+
Scope: SELF-CONTAINED definitions with inline layouts (generated actions above all). Hand-authored actions that receive triggers from fragments or bind stored layouts should audit the COMPOSED definition, or skip.
|
|
494
|
+
|
|
495
|
+
---
|
|
496
|
+
|
|
497
|
+
## Quick reference
|
|
498
|
+
|
|
499
|
+
```ts
|
|
500
|
+
type ActionDefinition = {
|
|
501
|
+
id: string;
|
|
502
|
+
name?: string;
|
|
503
|
+
description?: string;
|
|
504
|
+
title?: string; // resolvable instance label for stack-nav chrome
|
|
505
|
+
layout?: LayoutNode | string;
|
|
506
|
+
data?: Record<string, unknown>;
|
|
507
|
+
input?: Record<string, unknown>; // JSON Schema — the openable-input contract
|
|
508
|
+
triggers?: TriggerConfig[];
|
|
509
|
+
endpoints?: Record<string, EndpointConfig>;
|
|
510
|
+
lifecycle?: LifecycleConfig;
|
|
511
|
+
};
|
|
512
|
+
|
|
513
|
+
type TriggerConfig = {
|
|
514
|
+
event?: string; // OR message
|
|
515
|
+
message?: string;
|
|
516
|
+
ref?: string;
|
|
517
|
+
do: Step[];
|
|
518
|
+
};
|
|
519
|
+
|
|
520
|
+
type Step = Mutation | Effect;
|
|
521
|
+
|
|
522
|
+
// Mutations
|
|
523
|
+
{ set: string, value: unknown }
|
|
524
|
+
{ set: string, from: string }
|
|
525
|
+
{ toggle: string }
|
|
526
|
+
{ increment: string, by?: number }
|
|
527
|
+
{ decrement: string, by?: number }
|
|
528
|
+
{ push: string, value: unknown }
|
|
529
|
+
{ pop: string }
|
|
530
|
+
{ removeAt: string, index: number | string }
|
|
531
|
+
{ move: string, from: number | string, to: number | string }
|
|
532
|
+
{ clear: string }
|
|
533
|
+
{ reset: true }
|
|
534
|
+
|
|
535
|
+
// Effects
|
|
536
|
+
{ call: string, onSuccess?: Step[], onError?: Step[] }
|
|
537
|
+
{ emit: { channel: string, payload?: unknown } }
|
|
538
|
+
{ push: { action: string, canvas?: string, input?: object, with?: string[] } }
|
|
539
|
+
{ pop: true }
|
|
540
|
+
{ replace: { action: string, canvas?: string, input?: object, with?: string[] } }
|
|
541
|
+
{ popTo: { canvas?: string, instance: string } }
|
|
542
|
+
{ resetTo: { action: string, canvas?: string, input?: object, with?: string[] } }
|
|
543
|
+
{ removeInstance: { canvas?: string, instance: string } }
|
|
544
|
+
{ removeSelf: true }
|
|
545
|
+
{ reload: true }
|
|
546
|
+
|
|
547
|
+
// Endpoints (EndpointConfig = HTTP | Function)
|
|
548
|
+
{ url: string, method: string, headers?: object, request?: unknown, response?: unknown, target?: string, errorTarget?: string }
|
|
549
|
+
{ fn: string, target?: string, errorTarget?: string }
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
For wiring actions onto a canvas via the shell, see `SHELL_DOCS.md`. For the layout language actions render through, see `LAYOUT_DOCS.md`.
|