Node wizards: guided creation for ADRs, requirements and other governance elements

[tomasz-zajac-oss]

Creating an ADR used to mean dropping it on the canvas and then filling in a wall of fields in the properties panel, with the relations that give it meaning (what it constrains, what it supersedes) left for later or forgotten. Node types can now carry a wizard: a step-by-step form with guidance per step that ends with those relations.

What the user sees

• Creating an ADR, fitness function, requirement, scenario or mockup opens its wizard wherever the element is created:
  • canvas: palette drop or double-click;
  • table view: palette drop;
  • wiki: "Add child".
• The element is only created when the wizard finishes, together with its relations, as one undo step. Esc / Cancel creates nothing. Create (or ⌘/Ctrl+Enter) works from any step, so the wizard never blocks; only the name is required.
• Relation steps list only the elements the relation type allows. Example: an ADR's "Affected elements" step offers C4 elements for constrains, and its "Supersedes" step offers other ADRs.
• The requirement wizard has a "Sentence" step: one EARS sentence fills in the EARS fields (reuses EarsQuickEntry).
• "Fill in with wizard…" in the properties panel reopens the wizard for an existing element. Its current links start checked. Only changed values are written, and links are added or removed to match the checkboxes.
• "Wizard on create" in the app menu (Editing) turns the automatic wizard off. Stored in studio settings, not in the document.

How it's built

• Metamodel data. NodeTypeDef.wizard in packages/common/src/metamodel/types.ts has trigger: 'create' | 'manual', prefill (supports {{today}}) and steps. A step is one of:

  • fields (property keys plus label / description);
  • relations (relation type + direction);
  • custom (a built-in editor; only ears-quick-entry so far).

  Custom metamodels can define wizards, and they round-trip through every format that stores the metamodel. Documents on the built-in governance preset get the wizards with no migration, because the preset is rebuilt from code on load.

• Helpers. Pure functions in packages/common/src/metamodel/wizard.ts: visible fields per step (honours visibleWhen), relation candidates, missing required fields, a node's existing links.

• One entry point in the store (packages/ui/src/store/diagramStore.ts):

  • requestCreateNode(node, { links, onCreated, skipWizard }): opens a wizard session if the type has a create-time wizard, otherwise creates the node and its links at once. The metamodel's placement and cardinality checks run before the wizard opens, not after the user has filled it in.
  • finishNodeWizard, cancelNodeWizard, openNodeWizard.
  • addNode is unchanged, so AI tools, Hub import and internal operations never open a wizard.

• Wiki "Add child" now passes the hierarchy relation (derives) as a link instead of an onCreated callback. The wizard shows it pre-checked, and the store skips duplicate relations.

• Mounting. NodeWizard is mounted once in Studio's App.tsx, which covers the web build and the VS Code webview. The Hub viewer is read-only and unaffected.

Tests

• Unit, common: packages/common/tests/nodeWizard.test.ts, 11 tests. Covers the helpers, plus a check that every preset wizard refers to properties and relation types that exist.
• Unit, ui: packages/ui/tests/nodeWizard.test.ts, 11 tests. Covers:
  • the wizard opens instead of creating, and direct creation when it is off or skipped;
  • early refusal;
  • finish creates values and links as one undo step;
  • cancel never fires the callback;
  • edit mode adds and removes links and leaves unrelated relations alone.
• E2E: apps/e2e/tests/studio/wizard.spec.ts:
  • drop an ADR on the canvas, fill it in, link Bookstore, check the saved document;
  • Esc creates nothing;
  • the same wizard from the table view.

npm test, npm run typecheck and the full e2e suite pass locally (e2e: 54 passed; the 4 known-issues tests are test.fail as before). Checked by hand in the web build: the ADR and requirement wizards in the dark and light themes, and "Fill in with wizard…". Not tried in the desktop app.

Still open

Listed in docs/IMPROVEMENTS.md under "Node wizards", among them:

• the metamodel editor can't edit wizards yet (custom types need the JSON);
• "Fill in with wizard…" exists only in the properties panel;
• a canvas palette drop still names the element after its type id ("Adr"), as before;
• linking supersedes doesn't mark the older ADR as superseded.

🤖 Generated with Claude Code