@teurons/vds-diagrams 0.0.0-stage → 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 +170 -2
- package/dist/cli.js +2244 -0
- package/dist/diagrams.css +991 -0
- package/dist/grid.d.ts +1 -0
- package/dist/grid.js +283 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2044 -0
- package/dist/skills/vds-aggregates/SKILL.md +115 -0
- package/dist/skills/vds-ask-or-park/SKILL.md +101 -0
- package/dist/skills/vds-book-to-spec/SKILL.md +136 -0
- package/dist/skills/vds-build-from-published/SKILL.md +89 -0
- package/dist/skills/vds-change/SKILL.md +113 -0
- package/dist/skills/vds-context-map/SKILL.md +125 -0
- package/dist/skills/vds-contexts/SKILL.md +134 -0
- package/dist/skills/vds-diagrams/SKILL.md +88 -0
- package/dist/skills/vds-entities-and-values/SKILL.md +108 -0
- package/dist/skills/vds-language/SKILL.md +106 -0
- package/dist/skills/vds-model-review/SKILL.md +123 -0
- package/dist/skills/vds-ports-and-adapters/SKILL.md +119 -0
- package/dist/skills/vds-publish/SKILL.md +123 -0
- package/dist/skills/vds-reframe/SKILL.md +122 -0
- package/dist/skills/vds-requirements/SKILL.md +128 -0
- package/dist/skills/vds-requirements-review/SKILL.md +121 -0
- package/dist/skills/vds-scenarios/SKILL.md +142 -0
- package/dist/skills/vds-slice-blocks/SKILL.md +127 -0
- package/dist/skills/vds-story-walk/SKILL.md +128 -0
- package/dist/skills/vds-strip-invented/SKILL.md +130 -0
- package/dist/skills/vds-subdomains/SKILL.md +127 -0
- package/dist/skills/vds-which-skill/FILE-SHAPES.md +312 -0
- package/dist/skills/vds-which-skill/SKILL.md +125 -0
- package/dist/types/diagrams/src/grid/camera.d.ts +32 -0
- package/dist/types/diagrams/src/grid/capability.d.ts +11 -0
- package/dist/types/diagrams/src/grid/fold-uj.d.ts +2 -0
- package/dist/types/diagrams/src/grid/grid-canvas.d.ts +95 -0
- package/dist/types/diagrams/src/grid/index.d.ts +5 -0
- package/dist/types/diagrams/src/grid/input.d.ts +93 -0
- package/dist/types/diagrams/src/grid/route.d.ts +21 -0
- package/dist/types/engine/js/bridge.d.ts +12 -0
- package/dist/types/engine/js/index.d.ts +73 -0
- package/dist/types/vds-diagrams/src/canvas.d.ts +43 -0
- package/dist/types/vds-diagrams/src/from-scenarios.d.ts +4 -0
- package/dist/types/vds-diagrams/src/grid-folds.d.ts +1 -0
- package/dist/types/vds-diagrams/src/grid.d.ts +2 -0
- package/dist/types/vds-diagrams/src/index.d.ts +6 -0
- package/dist/types/vds-diagrams/src/types.d.ts +39 -0
- package/dist/types/vds-diagrams/src/user-journey.d.ts +54 -0
- package/dist/types/vds-diagrams/src/workspace.d.ts +25 -0
- package/dist/vds_engine.wasm +0 -0
- package/dist/workspace.d.ts +1 -0
- package/dist/workspace.js +113 -0
- package/package.json +68 -3
package/README.md
CHANGED
|
@@ -1,3 +1,171 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @teurons/vds-diagrams
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Draw scenario diagrams, capability diagrams and user journeys in React, on the same canvas the VDS studio uses.
|
|
4
|
+
|
|
5
|
+
There are two ways in:
|
|
6
|
+
|
|
7
|
+
| You have | Use |
|
|
8
|
+
|---|---|
|
|
9
|
+
| Just the screens and how a person moves between them, with no VDS workspace | A **user journey**: one JSON an AI or a person writes directly → `<CapabilityDiagram userJourney/>`, or `<ScenarioDiagram userJourney/>` when it is one path |
|
|
10
|
+
| A VDS workspace (its `domain/` folder) | Validate it, compile its scenario grids → `<ScenarioDiagram scenarioGrid/>`, `<CapabilityDiagram scenarioGrids/>` |
|
|
11
|
+
|
|
12
|
+
A diagram comes in two kinds and two views:
|
|
13
|
+
|
|
14
|
+
| Kind | What it is |
|
|
15
|
+
|---|---|
|
|
16
|
+
| Scenario diagram | One scenario of a capability, start to end, every step |
|
|
17
|
+
| Capability diagram | All of a capability's scenario grids, merged by screen |
|
|
18
|
+
|
|
19
|
+
| View | What it shows |
|
|
20
|
+
|---|---|
|
|
21
|
+
| Full | Every lane: the person, analytics, automation, commands, read models, event streams, other contexts |
|
|
22
|
+
| User journey (UJ) | The user journey: what the person acts on and sees (screens, decisions, SMS, email, a backend summary) |
|
|
23
|
+
|
|
24
|
+
The user journey view is a fixed fold of the full view. It is computed in the browser and never stored.
|
|
25
|
+
|
|
26
|
+
## Install
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
pnpm add @teurons/vds-diagrams react react-dom @teurons/ui
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`@teurons/vds-diagrams` is published to both public npm and GitHub Packages. Its canvas draws with Teurons UI (`@teurons/ui`), which is only on GitHub Packages, so a host maps the `@teurons` scope to GitHub and gives a token with `read:packages`. Both packages then come from there:
|
|
33
|
+
|
|
34
|
+
```ini
|
|
35
|
+
# .npmrc
|
|
36
|
+
@teurons:registry=https://npm.pkg.github.com
|
|
37
|
+
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
pnpm 10+ may refuse a version published in the last day (`minimumReleaseAge`); it then adds the package to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`, which you can keep.
|
|
41
|
+
|
|
42
|
+
## 0. A user journey, with no VDS workspace
|
|
43
|
+
|
|
44
|
+
A user journey lists the screens in order, the decisions after a screen (each way a check of its own), the SMS and email messages the person receives, and notes on what the system does. A screen may carry its own json-render spec, and the canvas draws it inside the screen's box using your renderer.
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"kind": "journey", "input": 1, "title": "Sign up", "persona": "Investor",
|
|
49
|
+
"screens": [
|
|
50
|
+
{ "id": "mobile", "title": "Enter mobile", "render": { "root": "page", "elements": { } },
|
|
51
|
+
"errors": ["Enter a 10 digit mobile number"] },
|
|
52
|
+
{ "id": "otp", "title": "Verify mobile" },
|
|
53
|
+
{ "id": "mpin", "title": "Set MPIN" }
|
|
54
|
+
],
|
|
55
|
+
"decisions": [
|
|
56
|
+
{ "after": "mobile", "ways": [{ "when": "Mobile accepted", "to": "otp" }] },
|
|
57
|
+
{ "after": "otp", "ways": [{ "when": "New investor", "to": "mpin" }] }
|
|
58
|
+
],
|
|
59
|
+
"messages": [{ "id": "sms-code", "channel": "sms", "title": "SMS code", "after": "mobile" }],
|
|
60
|
+
"backend": [{ "under": "mobile", "title": "Send the code" }]
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
```tsx
|
|
65
|
+
'use client';
|
|
66
|
+
import { CapabilityDiagram, validateUserJourney, type UserJourney } from '@teurons/vds-diagrams';
|
|
67
|
+
import { JSONUIProvider, Renderer } from '@json-render/react';
|
|
68
|
+
|
|
69
|
+
const problems = validateUserJourney(userJourney); // [] when it can be drawn
|
|
70
|
+
<CapabilityDiagram
|
|
71
|
+
userJourney={userJourney}
|
|
72
|
+
renderScreen={(spec) => (
|
|
73
|
+
<JSONUIProvider registry={registry}><Renderer spec={spec} registry={registry} /></JSONUIProvider>
|
|
74
|
+
)}
|
|
75
|
+
/>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
With only a user journey there is one view, so the Full | UJ switch is hidden.
|
|
79
|
+
|
|
80
|
+
`<ScenarioDiagram userJourney={userJourney} />` draws a user journey that is one path: no screen may have more than one way out. `validateScenarioUserJourney(userJourney)` checks that, and the diagram shows the problems instead of drawing when it fails.
|
|
81
|
+
|
|
82
|
+
`userJourneyToGrid(userJourney)` returns the grid it draws, if you want the JSON.
|
|
83
|
+
|
|
84
|
+
## 1. Validate a VDS workspace first
|
|
85
|
+
|
|
86
|
+
Validate a workspace before drawing anything. Pass the files of its `domain/` folder as `{ path: text }` (`WorkspaceFiles`). Each path is relative to `domain/` (`contexts/BC-…/…`), never `domain/contexts/…`. `readWorkspaceFolder(dir)` builds that map on Node from a workspace or its `domain/` folder:
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import { checkWorkspace, compileScenarioGrids, readWorkspaceFolder } from '@teurons/vds-diagrams/workspace';
|
|
90
|
+
|
|
91
|
+
const files = await readWorkspaceFolder('./vds-workspace');
|
|
92
|
+
|
|
93
|
+
const report = await checkWorkspace(files); // { problems, incomplete, open }
|
|
94
|
+
// The engine (vds_engine.wasm) loads from beside the package; useEngineWasm(url) points elsewhere.
|
|
95
|
+
if (report.problems.length) throw new Error(report.problems.map((p) => p.message).join('\n'));
|
|
96
|
+
const grids = await compileScenarioGrids(files); // { 'DGSF-AUTH-5b88996a': grid, ... }
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
If you already have a compiled scenario grid (grid@1 JSON), validate that instead:
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
import { validateScenarioGrid } from '@teurons/vds-diagrams';
|
|
103
|
+
|
|
104
|
+
const problems = validateScenarioGrid(json); // [] when it can be drawn
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
From a terminal:
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
npx @teurons/vds-diagrams validate ./vds-workspace/domain # a workspace folder
|
|
111
|
+
npx @teurons/vds-diagrams validate ./DGSF-AUTH-5b88996a.grid.json
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## 2. Render
|
|
115
|
+
|
|
116
|
+
The canvas needs the browser, so in Next.js use it from a client component:
|
|
117
|
+
|
|
118
|
+
The canvas is drawn with Teurons UI (`@teurons/ui`) and React Flow, so the host needs their styles with Tailwind v4:
|
|
119
|
+
|
|
120
|
+
```css
|
|
121
|
+
@import "tailwindcss";
|
|
122
|
+
@import "@teurons/ui/styles.css";
|
|
123
|
+
@import "@xyflow/react/dist/style.css";
|
|
124
|
+
@import "@teurons/vds-diagrams/diagrams.css";
|
|
125
|
+
@source "../node_modules/@teurons/vds-diagrams/dist";
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
```tsx
|
|
129
|
+
'use client';
|
|
130
|
+
import { CapabilityDiagram, ScenarioDiagram } from '@teurons/vds-diagrams';
|
|
131
|
+
|
|
132
|
+
// One scenario diagram, full or user journey (default full).
|
|
133
|
+
<ScenarioDiagram scenarioGrid={grid} view="full" />
|
|
134
|
+
|
|
135
|
+
// A capability diagram, from all its scenario grids (default user journey).
|
|
136
|
+
<CapabilityDiagram scenarioGrids={Object.values(grids)} view="userJourney" />
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Next.js notes:
|
|
140
|
+
- create-next-app's `globals.css` sets `--background` and `--foreground` and flips them for dark mode. That overrides Teurons UI's colours, so delete that `:root` block. For dark mode put `class="dark"` on `<html>`.
|
|
141
|
+
- With Cache Components on (Next.js 16), load the workspace inside a `'use cache'` function or after `await connection()`.
|
|
142
|
+
- `checkWorkspace` and `compileScenarioGrids` run on the server; pass the grids to the client component as props.
|
|
143
|
+
|
|
144
|
+
The canvas fills its parent, so give the parent a height. Clicking a box opens its details beside the canvas, and the Full | UJ switch sits in the top-right corner.
|
|
145
|
+
|
|
146
|
+
## 3. Folds, without React
|
|
147
|
+
|
|
148
|
+
```ts
|
|
149
|
+
import {
|
|
150
|
+
foldCapabilityToUserJourney,
|
|
151
|
+
foldScenarioToUserJourney,
|
|
152
|
+
mergeScenarioGrids,
|
|
153
|
+
} from '@teurons/vds-diagrams/grid';
|
|
154
|
+
|
|
155
|
+
const uj = foldScenarioToUserJourney(grid); // a scenario diagram's user journey view
|
|
156
|
+
const cap = mergeScenarioGrids(Object.values(grids)); // a capability diagram, full view
|
|
157
|
+
const capUj = foldCapabilityToUserJourney(cap); // its user journey view
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Each one takes grid@1 JSON and returns grid@1 JSON.
|
|
161
|
+
|
|
162
|
+
## Skills
|
|
163
|
+
|
|
164
|
+
`dist/skills/` holds agent skills. Copy them into an agent's skills folder, for example `.claude/skills/`:
|
|
165
|
+
|
|
166
|
+
- `vds-diagrams`: validate, then render, and the grid@1 shape.
|
|
167
|
+
- `vds-*`: how to write a VDS spec 0.1 (story walk, requirements, scenarios, contexts, model, review and the rest). Start with `vds-which-skill`.
|
|
168
|
+
|
|
169
|
+
```sh
|
|
170
|
+
cp -R node_modules/@teurons/vds-diagrams/dist/skills/* .claude/skills/
|
|
171
|
+
```
|