Public connection path geometry: getPointOnPath(t)

オープン
#409 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
42/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
typescript

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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.
主要言語
TypeScript
スター
145
フォーク
12
平均マージ
1日 14時間
マージ済み PR(30日)
43

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

gravity-ui/graph のほかの issue

gravity-ui/graph の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。