You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -246,9 +246,23 @@ For a guided walkthrough, see [Demo Guide](docs/Demo.md).
246
246
247
247
For a deep dive into resource semantics — load, reload, invalidation, staleness, and runtime scoping — see the [Resources Guide](docs/Resources.md).
248
248
249
+
## Examples
250
+
251
+
The repository includes five runnable examples, each demonstrating a different set of Intent capabilities:
252
+
253
+
| Example | What it demonstrates |
254
+
|---------|---------------------|
255
+
|[`canonical-invite`](examples/canonical-invite)| Minimal screen: text ask, primary action, validation, blocked reasons, feedback, `inspectScreen()`. Matches the Quickstart one-to-one. |
256
+
|[`choice-form`](examples/choice-form)| All state kinds (text, choice, boolean) and ask kinds (`asChoice()`, `asSecret()`, `hint()`), multiple surfaces per screen, flow diagnostics, full test coverage. |
257
+
|[`resource-lifecycle`](examples/resource-lifecycle)| Full resource lifecycle: autoLoad, manual load, reload, invalidation, stale detection, failed state, action-driven invalidation with `.invalidates()`. |
|[`web-basic`](examples/web-basic)| Multi-screen team invite demo with router, resources, diagnostics panel, feedback, and keyboard default action. |
260
+
261
+
Each example includes tests. Run with `pnpm dev:<name>` (e.g. `pnpm dev:choice-form`) and test with `pnpm test` from the example directory.
262
+
249
263
## What the demo demonstrates
250
264
251
-
The demo is intentionally small. It is a dagger, not a cathedral.
265
+
The `web-basic`demo is intentionally small. It is a dagger, not a cathedral.
252
266
253
267
It demonstrates:
254
268
@@ -294,6 +308,9 @@ Diagnostics currently catch graph-level issues such as:
294
308
* Primary actions blocked without a human-readable reason
295
309
* Asks not included in a surface
296
310
* Actions not included in a surface
311
+
* Surfaces including nodes that no flow references
312
+
* Flow steps referencing nodes not in any surface
313
+
* Flows whose steps are entirely disconnected from surfaces
297
314
298
315
Diagnostics are not lint rules for HTML. They are semantic graph feedback.
299
316
@@ -356,6 +373,11 @@ Core rules:
356
373
357
374
## Roadmap
358
375
376
+
Completed:
377
+
378
+
* ✦ Three focused examples: `choice-form`, `resource-lifecycle`, `secret-vault` — covering all state kinds, choice/secret asks, multi-surface screens, resource lifecycle (autoLoad, reload, invalidation, failed state), complex flows, secret+private, and flow diagnostics
379
+
* ✦ DOM multi-surface rendering — each surface renders as a semantic `<section>` with surface-suffixed DOM ids, shared state, duplicate controls, and per-surface blocked reasons and feedback
Copy file name to clipboardExpand all lines: docs/Release-Readiness.md
+12-12Lines changed: 12 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
## Status
4
4
5
-
Three public alpha releases have been published: `0.1.0-alpha.0`, `0.1.0-alpha.1`, and `0.1.0-alpha.2`.
5
+
Seven public alpha releases have been published: `0.1.0-alpha.0` through `0.1.0-alpha.7`.
6
6
7
7
Five packages are under the `@intent-framework/*` scope, four of which are published to npm. The server package `@intent-framework/server` remains private and unpublished.
8
8
@@ -29,7 +29,7 @@ Packages under `examples/` (e.g., `web-basic`) are private and must not be publi
29
29
30
30
| Field | Value | Status |
31
31
|---|---|---|
32
-
| Current version |`0.1.0-alpha.1`| Acceptable for alpha |
32
+
| Current version |`0.1.0-alpha.7`| Acceptable for alpha |
33
33
|`main`|`./dist/index.js`| Exists after build |
34
34
|`module`|`./dist/index.js`| Exists after build |
35
35
|`types`|`./dist/index.d.ts`| Exists after build |
@@ -47,7 +47,7 @@ Packages under `examples/` (e.g., `web-basic`) are private and must not be publi
47
47
48
48
| Field | Value | Status |
49
49
|---|---|---|
50
-
| Current version |`0.1.0-alpha.2`| Acceptable for alpha |
50
+
| Current version |`0.1.0-alpha.7`| Acceptable for alpha |
51
51
|`main`|`./dist/index.js`| Exists after build |
52
52
|`module`|`./dist/index.js`| Exists after build |
53
53
|`types`|`./dist/index.d.ts`| Exists after build |
@@ -63,7 +63,7 @@ Packages under `examples/` (e.g., `web-basic`) are private and must not be publi
63
63
64
64
| Field | Value | Status |
65
65
|---|---|---|
66
-
| Current version |`0.1.0-alpha.1`| Acceptable for alpha |
66
+
| Current version |`0.1.0-alpha.7`| Acceptable for alpha |
67
67
|`main`|`./dist/index.js`| Exists after build |
68
68
|`module`|`./dist/index.js`| Exists after build |
69
69
|`types`|`./dist/index.d.ts`| Exists after build |
@@ -79,7 +79,7 @@ Packages under `examples/` (e.g., `web-basic`) are private and must not be publi
79
79
80
80
| Field | Value | Status |
81
81
|---|---|---|
82
-
| Current version |`0.1.0-alpha.1`| Acceptable for alpha |
82
+
| Current version |`0.1.0-alpha.7`| Acceptable for alpha |
83
83
|`main`|`./dist/index.js`| Exists after build |
84
84
|`module`|`./dist/index.js`| Exists after build |
85
85
|`types`|`./dist/index.d.ts`| Exists after build |
@@ -214,7 +214,7 @@ All post-publish steps use the `NPM_TOKEN` / `NODE_AUTH_TOKEN` from the `npm` en
214
214
215
215
### Publish cadence
216
216
217
-
- Currently publishing **alpha releases** (`0.1.0-alpha.0` through `0.1.0-alpha.2` so far)
217
+
- Currently publishing **alpha releases** (`0.1.0-alpha.0` through `0.1.0-alpha.7` so far)
218
218
- Use `Changesets` pre-release mode for alpha/beta
219
219
- Graduate to stable after API surface is settled and real-world usage begins
220
220
@@ -273,20 +273,20 @@ Do not manually create GitHub Releases.
A focused demonstration of the full resource lifecycle in Intent — autoLoad, manual load, reload, invalidation, stale detection, failed state, and action-driven invalidation.
4
+
5
+
## What it demonstrates
6
+
7
+
- Auto-loaded resource that reaches "ready" on screen start
8
+
-`autoLoad: false` resource that stays "idle" until explicitly loaded
9
+
-`resource.reload()` — transitions through "pending" back to "ready"
10
+
-`resource.invalidate()` — marks the resource stale without reloading
11
+
-`resource.load()` — manual load for `autoLoad: false` resources
12
+
-`.invalidates(resource)` on an action — marks resources stale on success
13
+
- Resource "failed" status when a loader throws
14
+
- Route-driven resource load context
15
+
16
+
## Run
17
+
18
+
```sh
19
+
pnpm install
20
+
pnpm dev:resource-lifecycle
21
+
```
22
+
23
+
Open the local URL printed by Vite. Use the browser console to inspect resource state.
24
+
25
+
## Test
26
+
27
+
```sh
28
+
pnpm test
29
+
```
30
+
31
+
Tests cover every resource status transition: autoLoad, idle, pending, ready, stale, failed, and action-driven invalidation.
32
+
33
+
## Inspect
34
+
35
+
- Watch the console log for resource load events and load counts
36
+
- Each reload increments the team version counter
37
+
- The "Broken save" action demonstrates a failed invalidation
38
+
- Test file (`src/ResourceDemo.test.ts`) shows the full resource API surface via `@intent-framework/testing`
|`asContact("email")`|`<input type="email">` with `autocomplete="email"`|
33
+
|`asSecret()`|`<input type="password">`|
34
+
|`$.state.boolean()`|`<input type="checkbox">`|
35
+
|`$.state.choice()` with `asChoice()`|`<select>` with `<option>` elements |
36
+
37
+
### Boolean and choice asks
38
+
39
+
Boolean asks render as checkboxes. The checked state is synced with the underlying `BooleanState`.
40
+
41
+
Choice asks render as `<select>` elements. Options are populated from the `ChoiceState` options array. The selected value is synced with the underlying state.
42
+
43
+
### Blocked reasons
44
+
45
+
When an action is disabled due to blocked reasons, the renderer adds:
46
+
47
+
-`disabled` attribute on the button
48
+
-`<p class="intent-blocked-reason" role="alert">` with the first blocked reason text
49
+
-`aria-describedby` on the button pointing to the reason element
50
+
51
+
When the action becomes enabled, the reason element is removed from the DOM and `aria-describedby` is cleared.
52
+
53
+
### Single-surface output
54
+
55
+
When a screen has exactly one surface, the output is backward compatible: a single `<main>` element containing one `<form>` with all asks and actions. No surface name suffix is added to DOM ids.
56
+
57
+
### Multi-surface output
58
+
59
+
When a screen has multiple surfaces, each surface renders as a separate `<section>` with `aria-label` set to the surface name. Each section contains its own `<form>` with only the items belonging to that surface.
60
+
61
+
**DOM id suffixes:** All ask inputs, buttons, hint paragraphs, reason paragraphs, and feedback outputs get a `--<surfaceName>` suffix to avoid id collisions.
62
+
63
+
**Duplicate controls share state:** The same ask appearing in multiple surfaces shares the underlying state. Typing in one surface updates the input in all surfaces.
64
+
65
+
**Duplicate action buttons:** The same action appearing in multiple surfaces renders separate buttons, all executing the same `executeAct()` call.
66
+
67
+
**Per-surface feedback:** Each surface gets its own `<output aria-live="polite">` element. Action feedback is updated independently per surface.
68
+
69
+
**`data-intent-*` semantic ids:** The `data-intent-ask` and `data-intent-action` attributes remain the same across all copies — they identify the semantic node, not the DOM position.
70
+
71
+
### Enter key default action
72
+
73
+
When exactly one primary action exists (or exactly one action total), pressing Enter in any text input triggers that action. The Enter hint ("Press Enter to ...") appears reactively when the default action becomes enabled, and is hidden when disabled. Shift/ Meta/ Ctrl/ Alt + Enter are ignored. Enter is ignored on `<textarea>`, `<select>`, and checkbox inputs.
74
+
75
+
### Options
76
+
77
+
```ts
78
+
renderDom(Screen, {
79
+
target: document.getElementById("root")!,
80
+
showScreenName: true, // render screen name as <h1>
0 commit comments