[v2 DX] Introduce LayerNext and migrate the layer authoring API

Aperta
#373 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
28/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
react, typescript
Ambito
design, frontend

Direzione di ricerca

Start with #374, then review #375 and #376 for the shared hosting, resource, lifecycle, and update contracts; #377 covers built-in migration, documentation, and public exports. Read the proposed LayerNext contract and its lifecycle tests before changing registration or React inference. Done means both layer models coexist, the tested resource and lifecycle semantics are explicit, built-ins and examples are migrated, migration docs are updated, and the listed strict, declaration, consumer, and CI checks pass.

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

Descrizione

Status and intent

Deferred design/implementation work. Capture the Layer DX proposal now and return to it later; do not expand the current strict-TypeScript PR or make this a prerequisite for the existing strict migration track.

Target branch: v2. Breaking layer contracts are possible before the v2 API is stabilized.

Related: #353 (strict TypeScript), #358 / #372 (current resource and lifecycle fixes), #360 (constructor/descriptor types), #363 (React inference), #364 and #365 (addon strict readiness). Reuse those improvements rather than duplicating their work.

Goal

Make custom layers straightforward to author, type, update and dispose. During development, allow the existing Layer and a new LayerNext to coexist so built-in layers can migrate incrementally.

Agreed direction

  • Keep the existing Layer operational during the transition.
  • Introduce LayerNext with its own author-facing contract; it must not inherit the old Layer props/lifecycle API.
  • Both models share an internal hosting mechanism for registration, rendering and resource ownership. Avoid maintaining two divergent engines.
  • Graph registration and React integration accept both models and preserve custom props and concrete instance/ref inference.
  • Move built-in layers and examples incrementally, with migration documentation.

Proposed new-model contract to refine before implementation

  • User props are separate from graph/camera/root dependencies and resource creation options.
  • Canvas-only, HTML-only, combined and resource-free modes express available resources accurately. A canvas mode provides a checked drawing context without user context assertions. Exact public syntax is a design decision for the first task; do not assume additional public layer classes are required.
  • canvas consistently means the layer's own canvas. Obtain the main graph canvas explicitly through the graph API rather than changing the meaning of context.graphCanvas between subclasses.
  • Attachment and permanent disposal have distinct semantics. Author hooks do not require calls to super or run from a base constructor before derived fields initialize.
  • Attach-scoped subscriptions, DOM resources and scheduled work have automatic cleanup; disposal also releases children and instance-lifetime resources.
  • Mutable props and immutable resource creation options have documented update semantics.

LayerNext is a transition name, not a commitment to two permanent public APIs. The proposed pre-release endpoint is to promote the new model to Layer and remove the old one; confirm release exports and migration timing before that final step.

Acceptance criteria

  • Both layer models work together throughout the transition without changing existing registration unexpectedly.
  • Custom props and concrete methods/refs are inferred in core and React, including generic custom classes.
  • Resource availability, attach/detach/reattach and permanent disposal have explicit, tested contracts.
  • Built-ins and examples demonstrate the new DX and the migration guide explains breaking changes.
  • Strict source/declaration checks, packed consumer contracts and required CI remain green after each independently mergeable PR.
  • The final public exports and retirement of the transition API are decided explicitly before release.

Work items and delivery order

  • #374 — Shared hosting, typed resources and authoring/registration contracts.
  • #375 — Attach scopes, cleanup and permanent disposal (after #374).
  • #376 — Predictable prop/presentation updates (after #374 and #375).
  • #377 — Incremental built-in migration, docs and final public exports (after #374–#376).
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.