Graph Dev

@gravity-ui/graph Development Workflow

Follow these phases in order. Skip to Phase 3 only for trivial one-line fixes.

Phase 1: Planning

Before writing any code, understand what you are touching. Read the relevant source files. Use EnterPlanMode for non-trivial features.

Architecture questions to answer:

1. Which layers are affected?

   Before deciding where to add or change something, discover all existing layers in the codebase:

   • Search src/ for classes that extend Layer to get the current full list
   • For each candidate layer, read its source to understand its zIndex, purpose, and what events it handles

   Identify the right layer:

   • Does an existing layer already do something close? Extend or modify it rather than creating a new one.
   • Is it purely visual without interaction? → probably GraphLayer or a new Canvas-only layer
   • Is it an HTML overlay? → use the html property in Layer constructor with transformByCameraPosition: true
   • Is it a new user interaction (drag, click, keyboard)? → check whether it fits into an existing interaction layer or needs a dedicated one

   If the task specifies which layer to use: read that layer's source, understand what it currently does, and verify the fit. If the specified layer seems wrong (wrong zIndex, wrong responsibility, event conflicts with existing handlers), raise the concern and clarify with the user before starting.

2. How do events propagate?

   • User input → which layer catches it? → which service processes it? → which store signals change? → which components re-render?
   • Are there events that need to be preventable via executеDefaultEventAction?

3. What are the data boundaries?

   • Store (RootStore, signals) — single source of truth
   • Canvas components read from store, never own authoritative state
   • React components sync via $viewComponent signal bridge

4. Does it touch the scheduler?

   • All Canvas rendering goes through the scheduler (RAF-batched)
   • Don't call render() directly — always performRender()
   • React updates are synchronous (via signals), Canvas updates are deferred

5. Are there circular dependency risks?

   • affectsUsableRect: false on HitBox to break cycles with boundary elements
   • Layers must not depend on each other directly

Output of this phase: A written plan with affected files, implementation approach, and potential risks.

Phase 2: DX/UX Analysis

After planning, forecast how the feature will be used — before writing a single line.

Developer Experience (DX)

• How does a library consumer configure this feature? Is the API consistent with existing patterns (e.g., graph.addLayer(MyLayer, props), graph.setEntities(...), useGraphEvent)?
• Are there footguns? (e.g., forgetting to call super.afterInit(), wrong coordinate space)
• Does it require boilerplate that could be hidden inside the library?

User Experience (UX)

• What does the end user see and feel?
• Are there edge cases that could produce unexpected visual behavior?
• Does interaction feel responsive (correct z-index stacking, correct hit regions)?

Critical rule

If a clean DX or UX requires compromises from the library — complexity, performance regressions, or incorrect behavior — eliminate the compromises, even at the cost of DX/UX.

The library is correct and performant first. API ergonomics are secondary. A footgun that the consumer can avoid with documentation beats a footgun baked into the library internals.

Output of this phase: A brief written DX/UX assessment. If you identified a tradeoff, explicitly state which side you chose and why.