Public connection path geometry: getPointOnPath(t)

Aperta
#409 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
42/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
typescript

Direzione di ricerca

Start by reading the connection implementations in packages/graph/src/components/canvas/connections/, especially bezierHelpers.ts and the createPath() methods for BaseConnection, BlockConnection, MultipointConnection, and BezierMultipointConnection. Then inspect GraphConnectionPO in packages/graph-playwright/src and its tests; implement the query to match each rendered path and verify the listed unit and E2E cases. Done means the public API, documentation, tests, and page object all satisfy the acceptance criteria.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Part of #396. Follow-up to #398.

Goal

Give connection components a public, typed way to answer "where is the point at fraction t of this connection's rendered path?", and make GraphConnectionPO in @gravity-ui/graph-playwright use it instead of its own copy of the bezier math.

#398 moved the page objects into @gravity-ui/graph-playwright without changing their behaviour. The geometry query listed there (item 4 of "Internals and implicit contracts touched today") was left out because it is a new core feature, not part of the extraction. This issue covers that part.

Target branch: v2. Depends on #398 (the package must exist).

Problem

GraphConnectionPO.getPointOnCurve() currently:

  1. reads getViewComponent().connectionPoints (start and end only) plus the useBezierConnections / bezierConnectionDirection config flags inside evaluate;
  2. re-implements generateBezierParams / getPointOfBezierCurve from packages/graph/src/components/canvas/connections/bezierHelpers.ts on the Node side.

This is wrong when the rendered path is not "one segment between two ports":

  • MultipointConnection draws curvePolyline(points) through TMultipointConnection.points; the page object ignores points and computes a point on the start–end chord, which can be far from the stroke. click() / hover() then miss the connection.
  • BezierMultipointConnection draws a bezier or a straight line per segment; same problem.
  • Custom connection components (configured through settings.connection) can draw anything; the page object can't know their shape.
  • Any change to the bezier helpers in core silently diverges from the copy in the page object.

Only the component that builds the path knows its geometry, so the query belongs on the component.

Responsibility

Core does:

  • Expose getPointOnPath(t) on BaseConnection and implement it for every built-in connection component, matching what createPath() draws.
  • Keep the implementation pure: no canvas access, no rendering side effects, no allocations beyond the returned point. Safe to call from evaluate in tests and from application code (label placement, tooltips, custom overlays).

Core does not:

  • Guarantee arc-length (constant-speed) parameterization. t follows the curve parameter, see the contract below.
  • Account for rounded polyline corners (curvePolyline corner radius) or line width. A returned point may be up to the corner radius away from the stroke at a polyline vertex; anywhere else it is on the path.
  • Change the existing hit-testing, arrow or label code. Reusing the query there is possible later and out of scope here.

@gravity-ui/graph-playwright does:

  • Call view.getPointOnPath(t) inside evaluate and return the result as GraphPoint.
  • Drop its own bezier math and stop reading useBezierConnections / bezierConnectionDirection.

Contract

class BaseConnection {
  /**
   * Point at fraction `t` of the rendered connection path, in world coordinates.
   * `t = 0` is the source end, `t = 1` the target end.
   * Returns `undefined` when the connection has no geometry yet
   * (ports not resolved, multipoint connection with fewer than 2 points) or `t` is not finite.
   * `t` outside [0, 1] is clamped.
   */
  public getPointOnPath(t: number): TPoint | undefined;
}

Per component:

Component Path t mapping
BaseConnection (default) straight segment connectionPoints[0] → [1] linear interpolation
BlockConnection, useBezier: false straight segment (same as createPath()) linear interpolation
BlockConnection, useBezier: true cubic bezier from generateBezierParams(start, end, bezierDirection) getPointOfBezierCurve(start, end, t, bezierDirection) — same value the arrow uses at t = 0.5
MultipointConnection with points (≥ 2) polyline through points t spread across segments proportionally to segment length; linear inside a segment
MultipointConnection without points falls back to BlockConnection as above
BezierMultipointConnection per segment: straight if aligned with bezierDirection, bezier otherwise (same rule as createPath()) t spread across segments proportionally to segment chord length; inside a segment, linear or bezier parameter

Rules:

  • The query must follow the same branch as createPath() for the current props/state. A subclass that overrides createPath() with a different shape should override getPointOnPath() too; this is stated in the JSDoc and in docs/connections/.
  • Zero-length segments are skipped; a path with total length 0 returns its single point for any t.
  • The method is public and documented in packages/graph/docs/connections/ (canvas connection system) next to createPath() / getPath().

Core changes

  • BaseConnection.getPointOnPath(t): straight interpolation between connectionPoints; undefined without geometry.
  • BlockConnection.getPointOnPath(t): bezier branch via the existing getPointOfBezierCurve (bezierHelpers.ts); straight branch via super.
  • MultipointConnection.getPointOnPath(t): polyline over getPoints(); fallback to super when there are no points; undefined for one point.
  • BezierMultipointConnection.getPointOnPath(t): per-segment bezier/straight using generateBezierParams, with the same isStraightSegment rule as createPath(). Extract that rule (and the segment iteration) into a shared helper so path building and the query cannot diverge.
  • Optional, if it falls out naturally: a small pure helper in bezierHelpers.ts (e.g. getPointOnPolyline(points, t)) reused by both multipoint classes.
  • Unit tests next to the components (*.test.ts, Jest + jest-canvas-mock).

@gravity-ui/graph-playwright changes

  • GraphConnectionPO.getPointOnCurve(time) becomes a single evaluate:

    const point = view.getPointOnPath(time);
    if (!point) throw new Error(`Connection ${connectionId} has no rendered geometry.`);
    return { x: point.x, y: point.y };
    

    Public names stay the same (getPointOnCurve, curveTime option, click() / hover()); the [0, 1] range check stays on the Node side.

  • Remove the duplicated bezier math and the getConfigFlag("useBezierConnections" | "bezierConnectionDirection") reads.

  • "Core API used inside page callbacks" in the package README / #398 contract: Connections row becomes getConnectionState(id) → $selected, getViewComponent().getPointOnPath(t); Settings row loses the two connection flags.

  • Peer range @gravity-ui/graph must point at a core version that has getPointOnPath (workspace dependency inside the monorepo; set the minimum version on release).

Migration

  • Core: additive, no breaking change. Custom connection components that override createPath() should also override getPointOnPath(); otherwise they inherit the parent's geometry (note in docs/migration-guides/v1-to-v2.md, "Connections" section).
  • @gravity-ui/graph-playwright: getPointOnCurve() / click() / hover() now follow the actual rendered path. For straight and single-bezier connections the result is unchanged; for multipoint and custom connections tests may hit a different (correct) point. This is the behaviour note already promised in #398's migration section; it lands with this issue.
  • In-repo callers: apps/e2e page objects that extend GraphConnectionPO need no change unless they read connectionPoints directly.

Acceptance criteria

  • BaseConnection.getPointOnPath(t: number): TPoint | undefined is public, typed, documented (JSDoc + docs/connections/), and implemented for BlockConnection, MultipointConnection, BezierMultipointConnection.
  • Unit tests: straight connection (t = 0, 0.5, 1; clamping; undefined without geometry and for non-finite t).
  • Unit tests: BlockConnection with bezier, bezierDirection "horizontal" and "vertical", values equal getPointOfBezierCurve for the same endpoints; endpoints returned exactly at t = 0 and t = 1.
  • Unit tests: MultipointConnection with 0 (fallback), 1 (undefined), 2 and ≥ 3 points, including a zero-length segment; vertices hit at the expected t.
  • Unit tests: BezierMultipointConnection with mixed straight and bezier segments in both directions.
  • GraphConnectionPO.getPointOnCurve() calls getPointOnPath inside evaluate; no bezier math or connection config flags remain in packages/graph-playwright/src.
  • E2E (apps/e2e, via GraphConnectionPO): click() selects a bezier connection (horizontal and vertical); click() selects a MultipointConnection whose points route away from the start–end chord (fails with the old implementation); hover() on the multipoint connection sets the hovered state.
  • Package contract still passes: the built @gravity-ui/graph-playwright has no runtime import of @gravity-ui/graph.
  • Existing build, typecheck, lint, strict (zero debt) and required CI checks stay green.
Lingua principale
TypeScript
Stelle
145
Fork
12
Merge medio
1g 14h
PR unite (30g)
43

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di gravity-ui/graph

Tutte le issue di gravity-ui/graph

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.