@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
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-which-skill
|
|
3
|
+
description: "Which skill a request about a VDS workspace needs: picks one or two of the nineteen VDS skills and their order, or says none fits. Use when work on a workspace is starting, when the right skill is unclear, when two skills both seem to fit, when the order of several is needed, or when a request may sit outside the set. A request that names its material goes straight to that material's skill."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Which skill now
|
|
7
|
+
|
|
8
|
+
Name one or two skills and the order to run them in, say why in one line, then run the first; four skills loaded at once means none is applied properly.
|
|
9
|
+
|
|
10
|
+
## Method
|
|
11
|
+
|
|
12
|
+
1. **Hear the phase.** Match what the person says to the phase table. Done when one phase is named, or the request matches no row.
|
|
13
|
+
2. **Read the state.** Run the commands under "Tell the phase from the workspace". The state wins over the phrase: "model it" on a step with no scenarios is still requirement discovery. Done when the first matching row of that table is named.
|
|
14
|
+
3. **Pick the material.** Inside a phase each skill is named after what it works on. When two fit, use the Overlaps table; do not read both skills. Done when one or two skills are named.
|
|
15
|
+
4. **Say it and start.** One line: the skills, the order, the reason. More than one step ahead comes from Stacking, three skills at most. Done when the first skill is running, or the "nothing fits" sentence was said.
|
|
16
|
+
|
|
17
|
+
## Phases
|
|
18
|
+
|
|
19
|
+
| Phase | The person is saying | Skills |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| Requirement discovery | "this is what we want; walk it with us" | vds-story-walk; then per step vds-requirements and vds-scenarios, which saves the step; vds-ask-or-park |
|
|
22
|
+
| Strategic design | "where does this belong", "these two words clash" | vds-subdomains, vds-contexts, vds-context-map |
|
|
23
|
+
| Tactical modeling | "the requirements are in, model it" | vds-slice-blocks for each step not modelled yet, then vds-aggregates, vds-entities-and-values, vds-ports-and-adapters |
|
|
24
|
+
| Review | "is this ready?", "did we really say that?" | vds-strip-invented, vds-requirements-review, vds-model-review |
|
|
25
|
+
| Publish | "freeze this capability", "sign off" | vds-publish |
|
|
26
|
+
| Change | "this has to change", about something published | vds-change |
|
|
27
|
+
| Build | "build it", "the tests ran" | vds-build-from-published |
|
|
28
|
+
| Any time | a new term, or two wordings | vds-language |
|
|
29
|
+
| Any time | "no, you have this wrong" | vds-reframe |
|
|
30
|
+
|
|
31
|
+
## Tell the phase from the workspace
|
|
32
|
+
|
|
33
|
+
Run `vds status`, `vds index` and `vds check` (MCP: `vds_status`, `vds_index`, `vds_check`). None of them writes. If the connected `vds` MCP server offers no `vds_index`, it is an older server: use the CLI for every step, run from source (`node apps/cli/src/bin.ts`), and tell the person once. `vds status` prints the revision every `--base <rev>` takes, and each write prints the next one; file paths are in the workspace's `VDS.md`. When you write a file whose whole shape no skill shows, read `FILE-SHAPES.md` beside this skill. Walk the rows top to bottom; the first that fits wins.
|
|
34
|
+
|
|
35
|
+
| The workspace shows | Go to |
|
|
36
|
+
|---|---|
|
|
37
|
+
| `vds index` lists no context of kind `ours` | vds-contexts (day 1) |
|
|
38
|
+
| A context of kind ours and no capability for this story | vds-story-walk |
|
|
39
|
+
| `vds status` says `equal` or `differs` and the person asks for an edit, or the build found a missing or wrong scenario | vds-change |
|
|
40
|
+
| `vds status` says `never-published` and the person asks for an edit | the skill that owns the material |
|
|
41
|
+
| The person asks "is it ready?" or to review a capability | vds-requirements-review, then vds-model-review |
|
|
42
|
+
| The person asks to publish | vds-publish |
|
|
43
|
+
| A capability with no requirements, or walked steps with no requirement | per step vds-requirements, then vds-scenarios, which saves the step |
|
|
44
|
+
| An open hot spot names a step that could not be saved, and the answer has come | the skill that owns the answer, then vds-scenarios saves the step |
|
|
45
|
+
| `vds check` prints `REQ-...: no SCN obeys it`, or a requirement has only the scenario that works | vds-scenarios |
|
|
46
|
+
| `vds check` prints "N step(s) not modelled yet" | vds-slice-blocks, one step at a time |
|
|
47
|
+
| A scenario needs a command, event or read model that does not exist, or the check refuses an automation for its wiring | vds-slice-blocks |
|
|
48
|
+
| `vds check` prints `on no Entity`, or an event is still filed with the capability | vds-aggregates |
|
|
49
|
+
| A rule sits on an attribute typed `string` or `integer` | vds-entities-and-values |
|
|
50
|
+
| `vds check` prints `no port to` or `no port for` | vds-ports-and-adapters |
|
|
51
|
+
| `is not on the context map` | vds-context-map |
|
|
52
|
+
| `is not in the language` | vds-language |
|
|
53
|
+
| "valid" and only open questions left | vds-ask-or-park, one question at a time |
|
|
54
|
+
| `vds status` shows a published version and the person wants code | vds-build-from-published |
|
|
55
|
+
|
|
56
|
+
`vds index` lists subdomains, people, contexts with their kind, and each capability's requirements with their type. It lists no scenario and no model block; read those with `vds show <ID>`.
|
|
57
|
+
|
|
58
|
+
## Overlaps
|
|
59
|
+
|
|
60
|
+
Each pair is one question. Ask it; do not load both.
|
|
61
|
+
|
|
62
|
+
| Torn between | Ask | Then |
|
|
63
|
+
|---|---|---|
|
|
64
|
+
| vds-ask-or-park / vds-reframe | Is one answer missing, or does every answer change what the thing is for? | Missing: ask-or-park. The premise: reframe. |
|
|
65
|
+
| vds-reframe / vds-change | Does `vds status` show `equal` or `differs`? | Yes: change owns it and runs reframe's listing and rebuild steps on the draft. `never-published`: reframe. |
|
|
66
|
+
| vds-reframe / the material's skill | Does more than one step, or a term's meaning, read differently after the correction? | Yes: reframe. One step, rule or limit: the material's skill. |
|
|
67
|
+
| vds-ask-or-park / vds-strip-invented | Is the session live, or are the requirements already written? | Live: ask-or-park. Written: strip-invented. |
|
|
68
|
+
| vds-strip-invented / vds-requirements-review | Is the question "who said this?" or "is this ready?" | Who said: strip-invented, and it runs first. Ready: requirements-review. |
|
|
69
|
+
| vds-story-walk (read-back) / vds-requirements-review | Is the writer confirming the walk is whole, or is another agent judging readiness? | Whole: story-walk. Ready: requirements-review. |
|
|
70
|
+
| vds-requirements-review / vds-model-review | Is it the story, or the commands, events, aggregates and ports? | Story: requirements-review. Blocks: model-review. |
|
|
71
|
+
| vds-requirements / vds-slice-blocks | For an automation: the statement and type, or its trigger, read model, sees and command? | Statement: requirements, wiring left empty. Wiring: slice-blocks, now or in a later session. |
|
|
72
|
+
| vds-scenarios / vds-slice-blocks | Wording an outcome with the person, or writing the blocks a saved step names? | Plain words, `exits`, `start` and saving the step: scenarios. Block files: slice-blocks. |
|
|
73
|
+
| vds-requirements / vds-scenarios | Is a rule missing from the statement, or stated and without an example? | Missing: requirements first. No example: scenarios. |
|
|
74
|
+
| vds-slice-blocks / vds-aggregates | Deriving the command and events, or deciding which aggregate owns them? | Deriving: slice-blocks. Owning: aggregates. |
|
|
75
|
+
| vds-aggregates / vds-entities-and-values | Which rules must hold together, or does this thing have an identity or a rule on its value? | Together: aggregates. Identity or value: entities-and-values. |
|
|
76
|
+
| vds-context-map / vds-ports-and-adapters | For the anticorruption layer: does this relation translate, or how is the translation built? | The ACL role on the relation: context-map. The port and adapter: ports-and-adapters. |
|
|
77
|
+
| vds-entities-and-values / vds-context-map | For an external event's attributes: which fields arrive, or what type each gets? | Fields: context-map. Types: entities-and-values. |
|
|
78
|
+
| vds-language / vds-contexts | One word, two meanings: is the word being recorded, or the boundary decided? | Record both meanings as a clash: language. The split, on the person's yes: contexts. |
|
|
79
|
+
| vds-language / vds-change | A rename with the meaning unchanged: is the capability published? | No: language renames everywhere in one change. Yes: change orders it, language renames. A changed meaning: reframe or change. |
|
|
80
|
+
| vds-contexts / vds-subdomains | Where a boundary goes, or how much a part of the business matters? | Boundary, kind and the day-1 working mark (one question): contexts. Core, supporting, generic after that: subdomains. |
|
|
81
|
+
| vds-contexts / vds-context-map | Does the outside system have a context yet? | No: contexts opens it. Yes: context-map relates it. |
|
|
82
|
+
| vds-change / vds-publish | Does the person want an edit, or a decision on the draft as it stands? | Edit: change, then publish. Decision: publish. |
|
|
83
|
+
| vds-build-from-published / vds-change | Does the code lack something the published copy never said, or is the published copy wrong? | Never said: ask-or-park. Wrong, or a scenario missing: change, never straight to scenarios. |
|
|
84
|
+
|
|
85
|
+
## Stacking
|
|
86
|
+
|
|
87
|
+
Run in sequence. Name at most three at once; name the next when the last one ends.
|
|
88
|
+
|
|
89
|
+
- **Day 1**: vds-contexts (one working context and subdomain, the working mark from one question), then vds-story-walk.
|
|
90
|
+
- **A requirement discovery session**: vds-story-walk to the end of the story. Then per step: vds-requirements and vds-scenarios word it with the person and save it. vds-slice-blocks models it, then or in a later session. A step that cannot be saved becomes a hot spot. vds-ask-or-park and vds-language cut in at a gap or a new word and hand back.
|
|
91
|
+
- **After a session**: vds-strip-invented, then vds-contexts for the clues the session left. vds-subdomains or vds-context-map follow only when a context was added or renamed.
|
|
92
|
+
- **Modeling the saved steps**: vds-slice-blocks per step, then vds-aggregates, then vds-entities-and-values. vds-ports-and-adapters comes once per context, after the developer says it is hexagonal.
|
|
93
|
+
- **Before publish**: the review of each half that changed since the last published copy (vds-requirements-review, vds-model-review), then vds-publish. A report is current until its half is edited. Both reviews run in an agent that did not write the material; if you wrote it, say so and hand the review over.
|
|
94
|
+
- **A change to something published**: vds-change. It names the skills to rerun, the reviews and vds-publish; follow its list.
|
|
95
|
+
- **"You have this wrong"**: `vds status` first. `never-published`: vds-reframe, which reruns the owning skills. Published: vds-change, as a premise change.
|
|
96
|
+
- **"Build it"**: vds-publish if the capability is `never-published`, then vds-build-from-published.
|
|
97
|
+
|
|
98
|
+
## Symptoms
|
|
99
|
+
|
|
100
|
+
| What you hear or see | Do |
|
|
101
|
+
|---|---|
|
|
102
|
+
| "set up all the contexts first" | vds-contexts opens one; the rest come from clues |
|
|
103
|
+
| "model it" and a step has no scenarios | vds-scenarios first; say why |
|
|
104
|
+
| "is it ready?" and you wrote the requirements | say a review needs another agent; do not review |
|
|
105
|
+
| "just fix it" inside a review | the review reports; the fix is a new run of the skill it names |
|
|
106
|
+
| a third small correction on one topic | ask whether one premise sits behind all three; yes: vds-reframe |
|
|
107
|
+
| "publish" and the draft changed after the reviews | the review the edit touches, then vds-publish |
|
|
108
|
+
| a request about the vds code, the studio or the book | outside this set; say so |
|
|
109
|
+
|
|
110
|
+
## When nothing fits
|
|
111
|
+
|
|
112
|
+
Say: "No VDS skill covers this. I will answer without one, and here is what is missing: <the gap>." Then answer plainly, or park the point through vds-ask-or-park when it is a question for a person.
|
|
113
|
+
|
|
114
|
+
The set does not cover:
|
|
115
|
+
|
|
116
|
+
- **Why a capability exists.** Goals, value and the business case have no material; spec 0.1 has no field for what a capability is for.
|
|
117
|
+
- **A story across contexts.** It is joined by commands and events and has no artifact; no skill walks it. A premise wrong across two contexts runs vds-reframe once per context.
|
|
118
|
+
- **Priorities and slices of a release.** Ranking hot spots, ordering capabilities, estimates and who builds what.
|
|
119
|
+
- **Writing the code.** vds-build-from-published pins versions, names tests and records evidence; the test runner, code layout and architecture choice are outside.
|
|
120
|
+
- **Undoing a publish**, returning to an earlier published copy, or printing what differs between draft and published: no command exists.
|
|
121
|
+
- **The source of a statement.** No field records who said a rule or the answer to a hot spot.
|
|
122
|
+
- **Compiled flows and diagrams.** `vds compile`, `vds draw` and `vds generate` write them; no skill does.
|
|
123
|
+
- **Parts of the spec with no method yet:** partnership, shared kernel and separate ways on the context map, a context of kind legacy, sagas across aggregates, versioning an event, hosted sync.
|
|
124
|
+
|
|
125
|
+
Never stretch a skill over an uncovered case. A skill run outside its material gives a confident answer the person cannot tell from a real one.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/** A view: the zoom, and the sheet's offset on screen. */
|
|
2
|
+
export interface View {
|
|
3
|
+
s: number;
|
|
4
|
+
x: number;
|
|
5
|
+
y: number;
|
|
6
|
+
}
|
|
7
|
+
/** The screen's size in pixels. */
|
|
8
|
+
export interface ScreenSize {
|
|
9
|
+
w: number;
|
|
10
|
+
h: number;
|
|
11
|
+
}
|
|
12
|
+
/** The screen's and the sheet's size, the sheet in its own units. */
|
|
13
|
+
export interface CanvasSize extends ScreenSize {
|
|
14
|
+
W: number;
|
|
15
|
+
H: number;
|
|
16
|
+
}
|
|
17
|
+
/** A box on the sheet: its top-left corner and its size. */
|
|
18
|
+
export interface Rect {
|
|
19
|
+
x: number;
|
|
20
|
+
y: number;
|
|
21
|
+
w: number;
|
|
22
|
+
h: number;
|
|
23
|
+
}
|
|
24
|
+
export declare const MAX = 2.5;
|
|
25
|
+
export declare const GLIDE_MS = 380;
|
|
26
|
+
export declare const easeOut: (k: number) => number;
|
|
27
|
+
export declare function floorOf({ w, h, W, H }: CanvasSize, pills: HTMLElement[], cols: {
|
|
28
|
+
w: number;
|
|
29
|
+
}[]): number;
|
|
30
|
+
export declare function keep({ w, h, W, H }: CanvasSize, floor: number, v: View): View;
|
|
31
|
+
export declare function zoomAt(v: View, f: number, px: number, py: number, floor: number): View;
|
|
32
|
+
export declare function frame(self: Rect, group: Rect[], { w, h }: ScreenSize, floor: number): View;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { GridInput } from './input.js';
|
|
2
|
+
/** A grid with the side-panel details that ride beside it, keyed by box id. */
|
|
3
|
+
export type FlowWith<D> = GridInput & {
|
|
4
|
+
details?: Record<string, D>;
|
|
5
|
+
};
|
|
6
|
+
/** Every scenario flow of a capability as one grid: one column per screen. */
|
|
7
|
+
export declare function mergeScenarioGrids<D>(flows: FlowWith<D>[]): FlowWith<D>;
|
|
8
|
+
type Panel = Record<string, unknown>;
|
|
9
|
+
/** The capability flow folded to five lanes: what the persona does, sees and receives. */
|
|
10
|
+
export declare function foldCapabilityToUserJourney<D>(full: FlowWith<D>): FlowWith<D | Panel>;
|
|
11
|
+
export {};
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import { type GridArrow, type GridColumn, type GridInput, type LaidBox, type LaidRow } from './input.js';
|
|
2
|
+
import { type ComponentProps, type ComponentType, type ReactElement, type ReactNode } from 'react';
|
|
3
|
+
/** A box the canvas has picked: its anchor and the column it sits in. */
|
|
4
|
+
export interface Pick {
|
|
5
|
+
anchor: string;
|
|
6
|
+
station: string;
|
|
7
|
+
}
|
|
8
|
+
/** A column as the canvas draws it: keyed by its id, and always with a number. */
|
|
9
|
+
export interface CanvasColumn extends GridColumn {
|
|
10
|
+
key: string;
|
|
11
|
+
}
|
|
12
|
+
/** A row as the canvas draws it: keyed by its id. */
|
|
13
|
+
export interface CanvasRow extends LaidRow {
|
|
14
|
+
key: string;
|
|
15
|
+
}
|
|
16
|
+
/** What one cell of the canvas holds. */
|
|
17
|
+
export interface CanvasCell {
|
|
18
|
+
span?: number;
|
|
19
|
+
content: ReactNode;
|
|
20
|
+
}
|
|
21
|
+
/** The grid in the shape the parts read: keyed rows and columns, each cell's content. */
|
|
22
|
+
export interface Grid {
|
|
23
|
+
columns: CanvasColumn[];
|
|
24
|
+
rows: CanvasRow[];
|
|
25
|
+
cell(row: CanvasRow, column: CanvasColumn, ci: number): CanvasCell | null;
|
|
26
|
+
order: Record<string, number>;
|
|
27
|
+
edges: GridArrow[];
|
|
28
|
+
corner?: [string, string];
|
|
29
|
+
}
|
|
30
|
+
/** The button a host hands the zoom controls: Teurons' Button, or the plain one here. */
|
|
31
|
+
export type ZoomButton = ComponentType<{
|
|
32
|
+
variant?: string;
|
|
33
|
+
mode?: string;
|
|
34
|
+
size?: string;
|
|
35
|
+
'aria-label'?: string;
|
|
36
|
+
onClick?: () => void;
|
|
37
|
+
children?: ReactNode;
|
|
38
|
+
}>;
|
|
39
|
+
/** The props every canvas part takes. */
|
|
40
|
+
export interface RootProps extends Omit<ComponentProps<'div'>, 'onClick' | 'children'> {
|
|
41
|
+
grid: Grid;
|
|
42
|
+
picked?: Pick | null;
|
|
43
|
+
onPick?: (pick: Pick | null) => void;
|
|
44
|
+
children?: ReactNode;
|
|
45
|
+
}
|
|
46
|
+
/** The frame: owns the measured table, the camera, the wheel and the glide. */
|
|
47
|
+
declare function Root(props: RootProps): ReactElement;
|
|
48
|
+
/** What the axes take: the two words in the corner. */
|
|
49
|
+
export interface AxesProps {
|
|
50
|
+
corner?: [string, string];
|
|
51
|
+
/** Wraps a column's header button, as in a host's tooltip; the header is drawn as is without. */
|
|
52
|
+
renderColumn?: (column: Grid['columns'][number], header: ReactElement) => ReactElement;
|
|
53
|
+
}
|
|
54
|
+
declare function Axes({ corner, renderColumn, }: AxesProps): ReactElement;
|
|
55
|
+
declare function Viewport({ className, ...props }: ComponentProps<'div'>): ReactElement;
|
|
56
|
+
/** What the zoom controls take: the host's button, when it has one. */
|
|
57
|
+
export interface ZoomProps extends Omit<ComponentProps<'div'>, 'children'> {
|
|
58
|
+
Button?: ZoomButton;
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* − + Fit 100%, with the zoom as it is now. `Button` is the host's button component (it gets
|
|
62
|
+
* variant, mode, size, aria-label, onClick and children); a plain button when none is given.
|
|
63
|
+
*/
|
|
64
|
+
declare function Zoom({ className, Button, ...props }: ZoomProps): ReactElement;
|
|
65
|
+
/**
|
|
66
|
+
* The attributes every box carries, so the canvas can measure it, route arrows to it and pick
|
|
67
|
+
* it: a custom `renderBox` spreads these on its element.
|
|
68
|
+
*/
|
|
69
|
+
export declare const boxProps: (box: LaidBox, columnId: string) => {
|
|
70
|
+
'data-anchor': string;
|
|
71
|
+
'data-station': string;
|
|
72
|
+
'data-kind': string | undefined;
|
|
73
|
+
};
|
|
74
|
+
/** Everything the whole-canvas form takes: the input, and what draws its boxes and buttons. */
|
|
75
|
+
export interface GridCanvasProps extends Omit<RootProps, 'grid'> {
|
|
76
|
+
input: GridInput;
|
|
77
|
+
renderBox?: (box: LaidBox, columnId: string) => ReactNode;
|
|
78
|
+
renderColumn?: AxesProps['renderColumn'];
|
|
79
|
+
Button?: ZoomButton;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* The whole canvas from a grid input (input.ts): axes, the sheet, and the zoom buttons.
|
|
83
|
+
* `picked` is `{anchor, station}` or null; `onPick` gets the next one. `renderBox(box, columnId)`
|
|
84
|
+
* draws a box instead of the plain one, spreading `boxProps(box, columnId)` on its element.
|
|
85
|
+
* `Button` is the host's button component for the zoom controls.
|
|
86
|
+
*/
|
|
87
|
+
declare function GridCanvas({ input, picked, onPick, renderBox, renderColumn, Button, className, ...props }: GridCanvasProps): ReactElement;
|
|
88
|
+
/** A flow in one of its views: `full` draws the grid as compiled, `uj` its fold to what the
|
|
89
|
+
* persona acts on and sees (fold-uj.ts). Everything else passes to GridCanvas. */
|
|
90
|
+
export interface FlowProps extends Omit<GridCanvasProps, 'input'> {
|
|
91
|
+
grid: GridInput;
|
|
92
|
+
view?: 'full' | 'uj';
|
|
93
|
+
}
|
|
94
|
+
declare function Flow({ grid, view, ...props }: FlowProps): ReactElement;
|
|
95
|
+
export { Axes, Flow, GridCanvas, Root, Viewport, Zoom };
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { Axes, type AxesProps, type CanvasCell, type CanvasColumn, type CanvasRow, Flow, type FlowProps, type Grid, GridCanvas, type GridCanvasProps, type Pick, Root, type RootProps, Viewport, Zoom, type ZoomButton, type ZoomProps, boxProps, } from './grid-canvas.js';
|
|
2
|
+
export { GRID_INPUTS, type GridArrow, type GridBox, type GridColumn, type GridInput, type GridRow, type LaidBox, type LaidCell, type LaidColumn, type LaidRow, type Layout, type Side, layoutOf, problemsOf, } from './input.js';
|
|
3
|
+
export { type FlowWith, foldCapabilityToUserJourney, mergeScenarioGrids } from './capability.js';
|
|
4
|
+
export { foldScenarioToUserJourney } from './fold-uj.js';
|
|
5
|
+
export { type RoutedEdge, routeAll } from './route.js';
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/** The four sides of a box an arrow may leave or enter. */
|
|
2
|
+
export type Side = 'right' | 'left' | 'bottom' | 'top';
|
|
3
|
+
/** One column of the grid, left to right. */
|
|
4
|
+
export interface GridColumn {
|
|
5
|
+
id: string;
|
|
6
|
+
label?: string;
|
|
7
|
+
number?: string;
|
|
8
|
+
/** What the column's header shows on hover, one line each. */
|
|
9
|
+
hint?: string[];
|
|
10
|
+
}
|
|
11
|
+
/** One row of the grid, top to bottom; a `divider` row holds no box. */
|
|
12
|
+
export interface GridRow {
|
|
13
|
+
id: string;
|
|
14
|
+
label?: string;
|
|
15
|
+
sub?: string;
|
|
16
|
+
kind?: string;
|
|
17
|
+
}
|
|
18
|
+
/** One box, in one cell; `span` stretches it over the next columns. */
|
|
19
|
+
export interface GridBox {
|
|
20
|
+
id: string;
|
|
21
|
+
row: string;
|
|
22
|
+
column: string;
|
|
23
|
+
span?: number;
|
|
24
|
+
title: string;
|
|
25
|
+
kind?: string;
|
|
26
|
+
label?: string;
|
|
27
|
+
}
|
|
28
|
+
/** One arrow between two boxes, or a box and a port of it (`box#port`). */
|
|
29
|
+
export type GridArrow = {
|
|
30
|
+
from: string;
|
|
31
|
+
to: string;
|
|
32
|
+
label?: string;
|
|
33
|
+
tone?: string;
|
|
34
|
+
fromSide?: Side;
|
|
35
|
+
toSide?: Side;
|
|
36
|
+
labelAt?: 'start' | 'end';
|
|
37
|
+
bend?: 'early' | 'late';
|
|
38
|
+
/** `dots`: the arrow starts at a dot and its head points into a ring, both just outside the
|
|
39
|
+
* boxes, so neither hides under a box. */
|
|
40
|
+
ends?: 'dots';
|
|
41
|
+
/** `from`: the label starts with the number of the box the arrow leaves, as 2.3 Yes. */
|
|
42
|
+
numbered?: 'from';
|
|
43
|
+
};
|
|
44
|
+
/** The grid input, kind `grid`, input 1. */
|
|
45
|
+
export interface GridInput {
|
|
46
|
+
kind?: string;
|
|
47
|
+
input?: number;
|
|
48
|
+
spec?: string;
|
|
49
|
+
corner?: [string, string];
|
|
50
|
+
columns?: GridColumn[];
|
|
51
|
+
rows?: GridRow[];
|
|
52
|
+
boxes?: GridBox[];
|
|
53
|
+
arrows?: GridArrow[];
|
|
54
|
+
}
|
|
55
|
+
/** A column as laid out: it always shows a number. */
|
|
56
|
+
export interface LaidColumn extends GridColumn {
|
|
57
|
+
number: string;
|
|
58
|
+
}
|
|
59
|
+
/** A row as laid out: its kind is always one of the canvas's (`lane` when none is given). */
|
|
60
|
+
export interface LaidRow extends GridRow {
|
|
61
|
+
kind: string;
|
|
62
|
+
}
|
|
63
|
+
/** A box as laid out: `n` is its place in its column in reading order, `c` its column's index. */
|
|
64
|
+
export interface LaidBox extends GridBox {
|
|
65
|
+
n: number;
|
|
66
|
+
c: number;
|
|
67
|
+
}
|
|
68
|
+
/** One cell of the laid-out grid: how far it spans, and the boxes in it. */
|
|
69
|
+
export interface LaidCell {
|
|
70
|
+
span: number;
|
|
71
|
+
boxes: LaidBox[];
|
|
72
|
+
}
|
|
73
|
+
/** What the canvas draws: the grid in order, each cell's boxes, and the arrows. */
|
|
74
|
+
export interface Layout {
|
|
75
|
+
columns: LaidColumn[];
|
|
76
|
+
rows: LaidRow[];
|
|
77
|
+
cellAt(row: LaidRow, ci: number): LaidCell | null;
|
|
78
|
+
order: Record<string, number>;
|
|
79
|
+
reading: string[];
|
|
80
|
+
edges: GridArrow[];
|
|
81
|
+
corner?: [string, string];
|
|
82
|
+
}
|
|
83
|
+
/** The input versions this canvas reads. */
|
|
84
|
+
export declare const GRID_INPUTS: number[];
|
|
85
|
+
/** Every reason the input cannot be drawn, in plain words; none when it can. */
|
|
86
|
+
export declare function problemsOf(input: GridInput | undefined): string[];
|
|
87
|
+
/**
|
|
88
|
+
* The input laid out for the canvas: its columns and rows in order, each cell's boxes (with
|
|
89
|
+
* `n`, the box's place in its column in reading order, so 2.3 is the third box under column
|
|
90
|
+
* 2), each box's column for the router, and the arrows. Throws with every problem when the input
|
|
91
|
+
* cannot be drawn.
|
|
92
|
+
*/
|
|
93
|
+
export declare function layoutOf(input: GridInput): Layout;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { GridArrow } from './input.js';
|
|
2
|
+
import type { Rect } from './camera.js';
|
|
3
|
+
/** A point on the sheet, [x, y]. */
|
|
4
|
+
type Point = [number, number];
|
|
5
|
+
/** What the router hands the canvas: the path, the label's spot, its first point and its lines. */
|
|
6
|
+
export type RoutedEdge = GridArrow & {
|
|
7
|
+
/** Whether the arrow runs back to an earlier column. */
|
|
8
|
+
back: boolean;
|
|
9
|
+
id: string;
|
|
10
|
+
d: string;
|
|
11
|
+
mx: number;
|
|
12
|
+
my: number;
|
|
13
|
+
p1: Point;
|
|
14
|
+
/** Where it touches the box it points into. */
|
|
15
|
+
p2: Point;
|
|
16
|
+
lines: string[];
|
|
17
|
+
};
|
|
18
|
+
declare const HEAD = 8;
|
|
19
|
+
declare const TUCK = 4;
|
|
20
|
+
export { HEAD, TUCK };
|
|
21
|
+
export declare function routeAll(edges: GridArrow[], order: Record<string, number>, boxes: Record<string, Rect>): RoutedEdge[];
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** A compiled module as a running instance. A VDS module imports nothing. */
|
|
2
|
+
export declare function instanceOf(module: WebAssembly.Module): WebAssembly.Instance;
|
|
3
|
+
/** What a bound instance offers its callers. */
|
|
4
|
+
export interface Bridge {
|
|
5
|
+
/** Calls an export with text and returns its text. */
|
|
6
|
+
call(fn: string, input: string): string;
|
|
7
|
+
/** Calls an export with a value as JSON and returns its answer parsed. */
|
|
8
|
+
json(fn: string, input: unknown): unknown;
|
|
9
|
+
/** Calls an export that takes nothing and returns its answer parsed. */
|
|
10
|
+
none(fn: string): unknown;
|
|
11
|
+
}
|
|
12
|
+
export declare function bridge(instance: WebAssembly.Instance): Bridge;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/** Every spec file under domain/, as {path: text}. */
|
|
2
|
+
export type Files = Record<string, string>;
|
|
3
|
+
/** The engine refusing an input it cannot read. */
|
|
4
|
+
export interface SpecsError {
|
|
5
|
+
error: string;
|
|
6
|
+
}
|
|
7
|
+
/** One problem, with the rule that found it, the first ID it names and where that ID is defined. */
|
|
8
|
+
export interface Finding {
|
|
9
|
+
message: string;
|
|
10
|
+
/** The check that found it, as a stable kebab-case slug. */
|
|
11
|
+
rule: string;
|
|
12
|
+
id?: string;
|
|
13
|
+
path?: string;
|
|
14
|
+
line?: number;
|
|
15
|
+
/** A step not modelled yet: a block it names is not written. A draft may hold it; publish refuses it. */
|
|
16
|
+
incomplete?: true;
|
|
17
|
+
}
|
|
18
|
+
/** An entity the workspace defines: its ID, kind (the ID's prefix), name, file and mentions. */
|
|
19
|
+
export interface Entity {
|
|
20
|
+
id: string;
|
|
21
|
+
kind: string;
|
|
22
|
+
name: string;
|
|
23
|
+
path: string;
|
|
24
|
+
mentions: string[];
|
|
25
|
+
}
|
|
26
|
+
/** Everything a door draws, from one read: see packages/engine/src/v0_1/snapshot.rs. */
|
|
27
|
+
export interface EngineSnapshot {
|
|
28
|
+
spec: string;
|
|
29
|
+
problems: Finding[];
|
|
30
|
+
/** Steps not modelled yet: they never block a write, and publishing refuses them. */
|
|
31
|
+
incomplete: Finding[];
|
|
32
|
+
open: string[];
|
|
33
|
+
index: Entity[];
|
|
34
|
+
scenarios: string[];
|
|
35
|
+
/** Each compiled input as data by `kind@n`, `{path: input}`; null while there are problems or steps not modelled yet. */
|
|
36
|
+
inputs: Record<string, Record<string, unknown>> | null;
|
|
37
|
+
/** The paths the engine writes, as regular expressions over paths under domain/. */
|
|
38
|
+
owned: string[];
|
|
39
|
+
/** The strategic and model picture: subdomains, people, contexts, relationships, models, roots. */
|
|
40
|
+
glance?: unknown;
|
|
41
|
+
}
|
|
42
|
+
/** The engine's exports of spec 0.1, bound to one running instance. */
|
|
43
|
+
export interface Mapper {
|
|
44
|
+
/** Spec 0.1: every problem in a workspace, given {path: text} under domain/. */
|
|
45
|
+
check(files: Files): Finding[] | SpecsError;
|
|
46
|
+
/** Spec 0.1: each compiled flow as {path under domain/: text}; empty unless the workspace checks clean. */
|
|
47
|
+
flows(files: Files): Files | SpecsError;
|
|
48
|
+
/** Spec 0.1: what is not decided yet, as questions for a person; never a failure. */
|
|
49
|
+
open(files: Files): string[] | SpecsError;
|
|
50
|
+
/** Spec 0.1: the grid each compiled scenario flow is drawn on, as {path: text}; empty unless the workspace checks clean. */
|
|
51
|
+
grids(files: Files): Files | SpecsError;
|
|
52
|
+
/** Spec 0.1: each hexagonal context's compiled hexagon as {path under domain/: text}; empty unless the workspace checks clean. */
|
|
53
|
+
hexagons(files: Files): Files | SpecsError;
|
|
54
|
+
/** Spec 0.1: the context map's compiled input as {"diagrams/context-map.yaml": text}. */
|
|
55
|
+
contextMap(files: Files): Files | SpecsError;
|
|
56
|
+
/** Spec 0.1: the text of generated.yaml. */
|
|
57
|
+
generated(files: Files): string;
|
|
58
|
+
/** Spec 0.1: the index, one line per thing. */
|
|
59
|
+
index(files: Files): string;
|
|
60
|
+
/** Spec 0.1: problems, open questions, entities, scenarios, inputs and owned paths, in one parse. */
|
|
61
|
+
snapshot(files: Files): EngineSnapshot;
|
|
62
|
+
/** A value as YAML, the way the engine writes its files. */
|
|
63
|
+
toYaml(value: unknown): string;
|
|
64
|
+
/** A compiled input's YAML text as data. */
|
|
65
|
+
parseInput(text: string): unknown;
|
|
66
|
+
/** The paths the engine writes, as regular expressions. */
|
|
67
|
+
owned(): string[];
|
|
68
|
+
/** What publishing these capabilities (codes like AUTH) carries: paths under domain/. */
|
|
69
|
+
closure(files: Files, caps: string[]): string[];
|
|
70
|
+
}
|
|
71
|
+
export declare function bind(instance: WebAssembly.Instance): Mapper;
|
|
72
|
+
/** Instantiates the compiled module and binds its functions. */
|
|
73
|
+
export declare function instantiate(module: WebAssembly.Module): Mapper;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import type { ReactElement, ReactNode } from 'react';
|
|
2
|
+
import { type UserJourney } from './user-journey.js';
|
|
3
|
+
import type { DiagramGrid, DiagramView } from './types.js';
|
|
4
|
+
/** Draws a screen's or message's own json-render spec inside its box: the host's renderer. */
|
|
5
|
+
export type RenderScreen = (spec: unknown, box: {
|
|
6
|
+
id: string;
|
|
7
|
+
title: string;
|
|
8
|
+
}) => ReactNode;
|
|
9
|
+
/** What both diagrams share: the drawing's id, its first view and the host's screen renderer. */
|
|
10
|
+
interface DiagramProps {
|
|
11
|
+
id?: string;
|
|
12
|
+
view?: DiagramView;
|
|
13
|
+
/** Draws each screen's json-render spec inside its box. */
|
|
14
|
+
renderScreen?: RenderScreen;
|
|
15
|
+
}
|
|
16
|
+
/** A scenario diagram's data: its compiled scenario grid, or a user journey that is one path. */
|
|
17
|
+
type ScenarioDiagramProps = DiagramProps & ({
|
|
18
|
+
scenarioGrid: DiagramGrid;
|
|
19
|
+
userJourney?: never;
|
|
20
|
+
} | {
|
|
21
|
+
userJourney: UserJourney;
|
|
22
|
+
scenarioGrid?: never;
|
|
23
|
+
});
|
|
24
|
+
/** A capability diagram's data: its scenario grids, or a user journey written directly. */
|
|
25
|
+
type CapabilityDiagramProps = DiagramProps & ({
|
|
26
|
+
scenarioGrids: DiagramGrid[];
|
|
27
|
+
userJourney?: never;
|
|
28
|
+
} | {
|
|
29
|
+
userJourney: UserJourney;
|
|
30
|
+
scenarioGrids?: never;
|
|
31
|
+
});
|
|
32
|
+
/**
|
|
33
|
+
* One scenario on the canvas. From a scenario grid it opens in `view` (default full), with a
|
|
34
|
+
* Full | UJ switch. From a user journey it draws only the user journey view, and the journey
|
|
35
|
+
* must be one path: no screen with more than one way out, or its problems show instead.
|
|
36
|
+
*/
|
|
37
|
+
export declare function ScenarioDiagram(props: ScenarioDiagramProps): ReactElement;
|
|
38
|
+
/**
|
|
39
|
+
* A capability on the canvas: its scenario grids merged by screen, opening in `view` (default
|
|
40
|
+
* userJourney) with a Full | UJ switch; or a user journey, drawn in the user journey view only.
|
|
41
|
+
*/
|
|
42
|
+
export declare function CapabilityDiagram(props: CapabilityDiagramProps): ReactElement;
|
|
43
|
+
export {};
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { DiagramGrid } from './types.js';
|
|
2
|
+
import type { UserJourney } from './user-journey.js';
|
|
3
|
+
/** The user journey of the capability these scenario grids belong to (one capability only). */
|
|
4
|
+
export declare function capabilityUserJourney(scenarioGrids: DiagramGrid[], title: string): UserJourney;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { type FlowWith, foldCapabilityToUserJourney, foldScenarioToUserJourney, type GridArrow, type GridBox, type GridColumn, type GridInput, type GridRow, mergeScenarioGrids, } from '../../diagrams/src/grid/index.js';
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export { CapabilityDiagram, type RenderScreen, ScenarioDiagram } from './canvas.js';
|
|
2
|
+
export { type UserJourney, type UserJourneyBackendNote, type UserJourneyDecision, type UserJourneyMessage, type UserJourneyScreen, userJourneyToGrid, validateScenarioUserJourney, validateUserJourney, } from './user-journey.js';
|
|
3
|
+
export { validateScenarioGrid } from './grid.js';
|
|
4
|
+
export type { BoxDetail, BoxDetailRow, BoxDetailStep, DiagramGrid, DiagramView } from './types.js';
|
|
5
|
+
export { foldCapabilityToUserJourney, foldScenarioToUserJourney, mergeScenarioGrids, } from '../../diagrams/src/grid/index.js';
|
|
6
|
+
export { capabilityUserJourney } from './from-scenarios.js';
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import type { GridInput } from '../../diagrams/src/grid/index.js';
|
|
2
|
+
/** One labelled line of a box's side panel. */
|
|
3
|
+
export interface BoxDetailRow {
|
|
4
|
+
label: string;
|
|
5
|
+
value: string;
|
|
6
|
+
}
|
|
7
|
+
/** A REQ step a box spans, named by its requirement and scenario. */
|
|
8
|
+
export interface BoxDetailStep {
|
|
9
|
+
req: {
|
|
10
|
+
id: string;
|
|
11
|
+
title: string;
|
|
12
|
+
};
|
|
13
|
+
scn: {
|
|
14
|
+
id: string;
|
|
15
|
+
title: string;
|
|
16
|
+
};
|
|
17
|
+
}
|
|
18
|
+
/** What a box's side panel shows. */
|
|
19
|
+
export interface BoxDetail {
|
|
20
|
+
kind: string;
|
|
21
|
+
title: string;
|
|
22
|
+
rows: BoxDetailRow[];
|
|
23
|
+
steps: BoxDetailStep[];
|
|
24
|
+
/** What a box holds as lines: a screen's states and errors, the messages work sends. */
|
|
25
|
+
chips?: {
|
|
26
|
+
text: string;
|
|
27
|
+
tone: string;
|
|
28
|
+
port?: string;
|
|
29
|
+
}[];
|
|
30
|
+
/** A screen's or message's own json-render spec, drawn inside its box by the host's renderer. */
|
|
31
|
+
render?: unknown;
|
|
32
|
+
}
|
|
33
|
+
/** A scenario grid as the engine compiles it: grid@1 with its side panels and reading order. */
|
|
34
|
+
export interface DiagramGrid extends GridInput {
|
|
35
|
+
details?: Record<string, BoxDetail>;
|
|
36
|
+
reading?: string[];
|
|
37
|
+
}
|
|
38
|
+
/** Full: every lane as compiled. userJourney: folded to what the persona acts on and sees. */
|
|
39
|
+
export type DiagramView = 'full' | 'userJourney';
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import type { DiagramGrid } from './types.js';
|
|
2
|
+
/** One screen, in journey order. `render` is its json-render spec, drawn by the host's renderer. */
|
|
3
|
+
export interface UserJourneyScreen {
|
|
4
|
+
id: string;
|
|
5
|
+
title: string;
|
|
6
|
+
render?: unknown;
|
|
7
|
+
/** Lines a screen shows while the person stays on it: errors, then other states. */
|
|
8
|
+
errors?: string[];
|
|
9
|
+
states?: string[];
|
|
10
|
+
}
|
|
11
|
+
/** After a screen, each way on: when it holds, the person goes to `to`. Each way is its own check. */
|
|
12
|
+
export interface UserJourneyDecision {
|
|
13
|
+
after: string;
|
|
14
|
+
ways: {
|
|
15
|
+
when: string;
|
|
16
|
+
to: string;
|
|
17
|
+
}[];
|
|
18
|
+
}
|
|
19
|
+
/** A message the person receives, under the screen whose step sends it. */
|
|
20
|
+
export interface UserJourneyMessage {
|
|
21
|
+
id: string;
|
|
22
|
+
channel: 'sms' | 'email';
|
|
23
|
+
title: string;
|
|
24
|
+
after: string;
|
|
25
|
+
render?: unknown;
|
|
26
|
+
}
|
|
27
|
+
/** Something the system does under a screen, summed up in the Backend lane. */
|
|
28
|
+
export interface UserJourneyBackendNote {
|
|
29
|
+
under: string;
|
|
30
|
+
title: string;
|
|
31
|
+
}
|
|
32
|
+
/** A user journey, kind `journey`, input 1. */
|
|
33
|
+
export interface UserJourney {
|
|
34
|
+
kind: 'journey';
|
|
35
|
+
input: 1;
|
|
36
|
+
title: string;
|
|
37
|
+
persona?: string;
|
|
38
|
+
screens: UserJourneyScreen[];
|
|
39
|
+
decisions?: UserJourneyDecision[];
|
|
40
|
+
messages?: UserJourneyMessage[];
|
|
41
|
+
backend?: UserJourneyBackendNote[];
|
|
42
|
+
}
|
|
43
|
+
/** Every reason a user journey cannot be drawn; empty when it can. */
|
|
44
|
+
export declare function validateUserJourney(json: unknown): string[];
|
|
45
|
+
/**
|
|
46
|
+
* Every reason a user journey cannot be drawn as a scenario diagram; empty when it can. A
|
|
47
|
+
* scenario diagram follows one path, so no screen may have more than one way out.
|
|
48
|
+
*/
|
|
49
|
+
export declare function validateScenarioUserJourney(json: unknown): string[];
|
|
50
|
+
/**
|
|
51
|
+
* The user journey as grid@1 in the capability diagram's user journey view: Persona, Decision,
|
|
52
|
+
* SMS, Email, Backend.
|
|
53
|
+
*/
|
|
54
|
+
export declare function userJourneyToGrid(j: UserJourney): DiagramGrid;
|