@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.
Files changed (51) hide show
  1. package/README.md +170 -2
  2. package/dist/cli.js +2244 -0
  3. package/dist/diagrams.css +991 -0
  4. package/dist/grid.d.ts +1 -0
  5. package/dist/grid.js +283 -0
  6. package/dist/index.d.ts +1 -0
  7. package/dist/index.js +2044 -0
  8. package/dist/skills/vds-aggregates/SKILL.md +115 -0
  9. package/dist/skills/vds-ask-or-park/SKILL.md +101 -0
  10. package/dist/skills/vds-book-to-spec/SKILL.md +136 -0
  11. package/dist/skills/vds-build-from-published/SKILL.md +89 -0
  12. package/dist/skills/vds-change/SKILL.md +113 -0
  13. package/dist/skills/vds-context-map/SKILL.md +125 -0
  14. package/dist/skills/vds-contexts/SKILL.md +134 -0
  15. package/dist/skills/vds-diagrams/SKILL.md +88 -0
  16. package/dist/skills/vds-entities-and-values/SKILL.md +108 -0
  17. package/dist/skills/vds-language/SKILL.md +106 -0
  18. package/dist/skills/vds-model-review/SKILL.md +123 -0
  19. package/dist/skills/vds-ports-and-adapters/SKILL.md +119 -0
  20. package/dist/skills/vds-publish/SKILL.md +123 -0
  21. package/dist/skills/vds-reframe/SKILL.md +122 -0
  22. package/dist/skills/vds-requirements/SKILL.md +128 -0
  23. package/dist/skills/vds-requirements-review/SKILL.md +121 -0
  24. package/dist/skills/vds-scenarios/SKILL.md +142 -0
  25. package/dist/skills/vds-slice-blocks/SKILL.md +127 -0
  26. package/dist/skills/vds-story-walk/SKILL.md +128 -0
  27. package/dist/skills/vds-strip-invented/SKILL.md +130 -0
  28. package/dist/skills/vds-subdomains/SKILL.md +127 -0
  29. package/dist/skills/vds-which-skill/FILE-SHAPES.md +312 -0
  30. package/dist/skills/vds-which-skill/SKILL.md +125 -0
  31. package/dist/types/diagrams/src/grid/camera.d.ts +32 -0
  32. package/dist/types/diagrams/src/grid/capability.d.ts +11 -0
  33. package/dist/types/diagrams/src/grid/fold-uj.d.ts +2 -0
  34. package/dist/types/diagrams/src/grid/grid-canvas.d.ts +95 -0
  35. package/dist/types/diagrams/src/grid/index.d.ts +5 -0
  36. package/dist/types/diagrams/src/grid/input.d.ts +93 -0
  37. package/dist/types/diagrams/src/grid/route.d.ts +21 -0
  38. package/dist/types/engine/js/bridge.d.ts +12 -0
  39. package/dist/types/engine/js/index.d.ts +73 -0
  40. package/dist/types/vds-diagrams/src/canvas.d.ts +43 -0
  41. package/dist/types/vds-diagrams/src/from-scenarios.d.ts +4 -0
  42. package/dist/types/vds-diagrams/src/grid-folds.d.ts +1 -0
  43. package/dist/types/vds-diagrams/src/grid.d.ts +2 -0
  44. package/dist/types/vds-diagrams/src/index.d.ts +6 -0
  45. package/dist/types/vds-diagrams/src/types.d.ts +39 -0
  46. package/dist/types/vds-diagrams/src/user-journey.d.ts +54 -0
  47. package/dist/types/vds-diagrams/src/workspace.d.ts +25 -0
  48. package/dist/vds_engine.wasm +0 -0
  49. package/dist/workspace.d.ts +1 -0
  50. package/dist/workspace.js +113 -0
  51. package/package.json +68 -3
package/README.md CHANGED
@@ -1,3 +1,171 @@
1
- # Temporary Holding Version
1
+ # @teurons/vds-diagrams
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ ```