Skip to content

Commit 8a55087

Browse files
mahyarmlkmahyarmlk
authored
docs: add package-level readmes (#58)
1 parent 37a3cad commit 8a55087

5 files changed

Lines changed: 272 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,10 @@ Published packages:
5858

5959
| Package | npm |
6060
|---------|-----|
61-
| `@intent-framework/core` | Platformless semantic graph and runtime |
62-
| `@intent-framework/dom` | DOM materializer for screens and router |
63-
| `@intent-framework/router` | Typed route definitions and navigation |
64-
| `@intent-framework/testing` | Semantic test harness |
61+
| [`@intent-framework/core`](packages/core) | Platformless semantic graph and runtime |
62+
| [`@intent-framework/dom`](packages/dom) | DOM materializer for screens and router |
63+
| [`@intent-framework/router`](packages/router) | Typed route definitions and navigation |
64+
| [`@intent-framework/testing`](packages/testing) | Semantic test harness |
6565

6666
`@intent-framework/server` remains private and unpublished.
6767

@@ -196,10 +196,10 @@ This repository currently contains:
196196

197197
| Package | Purpose |
198198
| ----------------- | --------------------------------------- |
199-
| `@intent-framework/core` | Platformless semantic graph and runtime |
200-
| `@intent-framework/dom` | DOM materializer for screens and router |
201-
| `@intent-framework/router` | Typed route definitions and navigation |
202-
| `@intent-framework/testing` | Semantic test harness |
199+
| [`@intent-framework/core`](packages/core) | Platformless semantic graph and runtime |
200+
| [`@intent-framework/dom`](packages/dom) | DOM materializer for screens and router |
201+
| [`@intent-framework/router`](packages/router) | Typed route definitions and navigation |
202+
| [`@intent-framework/testing`](packages/testing) | Semantic test harness |
203203
| `@intent-framework/server` | Early server-side package |
204204

205205
The core package must remain platformless. It should not import DOM, React, router internals, server framework code, or native APIs.

‎packages/core/README.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# @intent-framework/core
2+
3+
Platformless semantic graph and runtime for Intent applications.
4+
5+
## Install
6+
7+
```sh
8+
pnpm add @intent-framework/core@0.1.0-alpha.1
9+
```
10+
11+
```sh
12+
npm install @intent-framework/core@0.1.0-alpha.1
13+
```
14+
15+
## What it provides
16+
17+
- `screen()` — define a semantic interaction space
18+
- `$.state.text()` / `$.state.boolean()` / `$.state.choice()` — reactive state
19+
- `$.ask()` — user-facing question with validation
20+
- `$.act()` — executable action with conditions, lifecycle, and feedback
21+
- `$.resource()` — async state with load/reload lifecycle
22+
- `$.surface()` — named containment surface
23+
- `createScreenRuntime()` — runtime that owns screen state and resources
24+
- `inspectScreen()` — semantic graph snapshot with diagnostics
25+
- Condition and signal primitives
26+
27+
## Minimal example
28+
29+
```ts
30+
import { screen, inspectScreen } from "@intent-framework/core"
31+
32+
const InviteMember = screen("InviteMember", $ => {
33+
const email = $.state.text("email")
34+
35+
const emailAsk = $.ask("Email", email)
36+
.required("Email is required")
37+
.validate(value => value.includes("@") ? true : "Enter a valid email")
38+
39+
const invite = $.act("Invite member")
40+
.primary()
41+
.when(emailAsk.valid, "Enter a valid email first")
42+
.does(() => {
43+
console.log("invite", email.value)
44+
})
45+
46+
$.surface("main").contains(emailAsk, invite)
47+
})
48+
49+
const graph = inspectScreen(InviteMember)
50+
console.log(graph.diagnostics)
51+
```
52+
53+
## Where this fits
54+
55+
Core defines the product graph. It has no DOM, React, Node, or framework dependencies. Renderers (`@intent-framework/dom`), the router (`@intent-framework/router`), and testing (`@intent-framework/testing`) all build on core.
56+
57+
## Learn more
58+
59+
- [Root README](../../README.md) — project overview and philosophy
60+
- [Quickstart](../../docs/Quickstart.md) — step-by-step guide
61+
- [Inspect Screen and Diagnostics Guide](../../docs/Inspect-Screen.md) — graph inspection and diagnostics
62+
- [Resources Guide](../../docs/Resources.md) — resource lifecycle and runtime scoping
63+
- [MVP Checkpoint](../../docs/MVP-Checkpoint.md) — current implementation boundaries
64+
65+
## Status
66+
67+
Experimental alpha. Version `0.1.0-alpha.1`. APIs may change. Not recommended for production use.

‎packages/dom/README.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# @intent-framework/dom
2+
3+
DOM materializer for Intent screens and router.
4+
5+
## Install
6+
7+
```sh
8+
pnpm add @intent-framework/core@0.1.0-alpha.1 @intent-framework/dom@0.1.0-alpha.1
9+
```
10+
11+
```sh
12+
npm install @intent-framework/core@0.1.0-alpha.1 @intent-framework/dom@0.1.0-alpha.1
13+
```
14+
15+
## What it provides
16+
17+
- `renderDom()` — materialize a screen into semantic HTML
18+
- `renderRouter()` — materialize a router into navigable DOM pages
19+
- Real HTML labels, inputs, buttons, and `aria-live` output
20+
- Reactive action enablement and blocked reasons
21+
- Enter key triggers the default action when unambiguous
22+
- Opt-in screen-name heading via `showScreenName`
23+
24+
## Minimal example
25+
26+
```ts
27+
import { screen } from "@intent-framework/core"
28+
import { renderDom } from "@intent-framework/dom"
29+
30+
const InviteMember = screen("InviteMember", $ => {
31+
const email = $.state.text("email")
32+
33+
const emailAsk = $.ask("Email", email)
34+
.required()
35+
.validate(value => value.includes("@") ? true : "Enter a valid email")
36+
37+
const invite = $.act("Invite member")
38+
.primary()
39+
.when(emailAsk.valid, "Enter a valid email first")
40+
41+
$.surface("main").contains(emailAsk, invite)
42+
})
43+
44+
const cleanup = renderDom(InviteMember, {
45+
target: document.getElementById("root")!,
46+
})
47+
```
48+
49+
The renderer produces real DOM — labels, inputs, buttons, and an `aria-live` output. No JSX required.
50+
51+
## Where this fits
52+
53+
DOM is a renderer for Intent screens. It depends on `@intent-framework/core` and can optionally integrate with `@intent-framework/router` via `renderRouter()`. It is not the source of truth — the screen definition is.
54+
55+
## Learn more
56+
57+
- [Root README](../../README.md) — project overview and philosophy
58+
- [Quickstart](../../docs/Quickstart.md) — step-by-step guide with DOM rendering
59+
- [Canonical runnable example](../../examples/canonical-invite) — matches the Quickstart one-to-one
60+
61+
## Status
62+
63+
Experimental alpha. Version `0.1.0-alpha.1`. APIs may change. Not recommended for production use.

‎packages/router/README.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# @intent-framework/router
2+
3+
Typed route definitions and navigation for Intent.
4+
5+
## Install
6+
7+
```sh
8+
pnpm add @intent-framework/core@0.1.0-alpha.1 @intent-framework/router@0.1.0-alpha.1
9+
```
10+
11+
```sh
12+
npm install @intent-framework/core@0.1.0-alpha.1 @intent-framework/router@0.1.0-alpha.1
13+
```
14+
15+
## What it provides
16+
17+
- `createRouter()` — typed, immutable route builder
18+
- `.route(name, path, screen)` — register a route with typed params
19+
- `.match(pathname)` — match a pathname to a route + screen
20+
- `.path(name, params)` — generate a typed path string
21+
- `RouterServices` — typed navigation service for screens and actions
22+
- `renderRouter()` integration lives in `@intent-framework/dom`
23+
24+
## Minimal example
25+
26+
```ts
27+
import { createRouter } from "@intent-framework/router"
28+
29+
type AppServices = {
30+
navigate: (name: string) => void
31+
}
32+
33+
const router = createRouter<AppServices>()
34+
.route("home", "/", HomeScreen)
35+
.route("team", "/team/:teamId", TeamScreen)
36+
.route("invite", "/team/:teamId/invite", InviteScreen)
37+
38+
const match = router.match("/team/abc123")
39+
if (match.found) {
40+
console.log(match.name, match.params) // "team", { teamId: "abc123" }
41+
}
42+
43+
const path = router.path("team", { teamId: "abc123" })
44+
console.log(path) // "/team/abc123"
45+
```
46+
47+
## Where this fits
48+
49+
Router provides typed route definitions and navigation for Intent screens. Use `@intent-framework/dom`'s `renderRouter()` to materialize navigation into the DOM. The router does not own the product model — it maps paths to screens.
50+
51+
## Learn more
52+
53+
- [Root README](../../README.md) — project overview and philosophy
54+
- [MVP Checkpoint](../../docs/MVP-Checkpoint.md) — current implementation boundaries
55+
- [Web basic example](../../examples/web-basic) — full demo with routing, resources, and diagnostics
56+
57+
## Status
58+
59+
Experimental alpha. Version `0.1.0-alpha.1`. APIs may change. Not recommended for production use.

‎packages/testing/README.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# @intent-framework/testing
2+
3+
Semantic test harness for Intent screens.
4+
5+
## Install
6+
7+
```sh
8+
pnpm add -D @intent-framework/testing@0.1.0-alpha.1
9+
```
10+
11+
```sh
12+
npm install --save-dev @intent-framework/testing@0.1.0-alpha.1
13+
```
14+
15+
## What it provides
16+
17+
- `testScreen()` — create a runtime and run semantic assertions
18+
- Answer asks by setting state directly
19+
- Assert action enabled/blocked state and blocked reasons
20+
- Execute actions through the runtime
21+
- Inspect feedback after action execution
22+
- Test resource load, reload, invalidation, and staleness
23+
24+
## Minimal example
25+
26+
```ts
27+
import { test, expect } from "vitest"
28+
import { testScreen } from "@intent-framework/testing"
29+
import { screen } from "@intent-framework/core"
30+
31+
const InviteMember = screen("InviteMember", $ => {
32+
const email = $.state.text("email")
33+
34+
const emailAsk = $.ask("Email", email)
35+
.required()
36+
.validate(value => value.includes("@") ? true : "Enter a valid email")
37+
38+
const invite = $.act("Invite member")
39+
.primary()
40+
.when(emailAsk.valid, "Enter a valid email first")
41+
42+
$.surface("main").contains(emailAsk, invite)
43+
})
44+
45+
test("invite is blocked until email is valid", async () => {
46+
await testScreen(InviteMember, async app => {
47+
await app.act("Invite member").toBeBlockedBy("Enter a valid email first")
48+
await app.answer("Email", "ada@example.com")
49+
await app.act("Invite member").toBeEnabled()
50+
})
51+
})
52+
53+
test("invite action can be executed", async () => {
54+
await testScreen(InviteMember, async app => {
55+
await app.answer("Email", "ada@example.com")
56+
await app.act("Invite member").run()
57+
})
58+
})
59+
```
60+
61+
No DOM, no selectors, no render waits. Tests speak product language.
62+
63+
## Where this fits
64+
65+
Testing provides a runtime harness for Intent screens. It depends on `@intent-framework/core`. Use it with any test runner (Vitest recommended). It pairs with `inspectScreen()` for diagnostics assertions.
66+
67+
## Learn more
68+
69+
- [Root README](../../README.md) — project overview and testing philosophy
70+
- [Quickstart](../../docs/Quickstart.md) — step-by-step guide with testing
71+
- [Canonical runnable example](../../examples/canonical-invite) — matches the Quickstart one-to-one
72+
73+
## Status
74+
75+
Experimental alpha. Version `0.1.0-alpha.1`. APIs may change. Not recommended for production use.

0 commit comments

Comments
 (0)