@populationgenomics/gene-glyph 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +58 -2
  3. package/dist/adapters/clinvar.d.ts +34 -0
  4. package/dist/adapters/clinvar.d.ts.map +1 -0
  5. package/dist/adapters/clinvar.test.d.ts +2 -0
  6. package/dist/adapters/clinvar.test.d.ts.map +1 -0
  7. package/dist/adapters/rmc.d.ts +31 -0
  8. package/dist/adapters/rmc.d.ts.map +1 -0
  9. package/dist/adapters/rmc.test.d.ts +2 -0
  10. package/dist/adapters/rmc.test.d.ts.map +1 -0
  11. package/dist/chrome/default-minimap.d.ts +26 -0
  12. package/dist/chrome/default-minimap.d.ts.map +1 -0
  13. package/dist/chrome/default-minimap.test.d.ts +2 -0
  14. package/dist/chrome/default-minimap.test.d.ts.map +1 -0
  15. package/dist/chrome/default-track-chevron.d.ts +37 -0
  16. package/dist/chrome/default-track-chevron.d.ts.map +1 -0
  17. package/dist/chrome/default-track-chevron.test.d.ts +2 -0
  18. package/dist/chrome/default-track-chevron.test.d.ts.map +1 -0
  19. package/dist/coordinate-mapper.d.ts +13 -0
  20. package/dist/coordinate-mapper.d.ts.map +1 -0
  21. package/dist/coordinate-mapper.test.d.ts +2 -0
  22. package/dist/coordinate-mapper.test.d.ts.map +1 -0
  23. package/dist/data-source.d.ts +24 -0
  24. package/dist/data-source.d.ts.map +1 -0
  25. package/dist/data-source.test.d.ts +2 -0
  26. package/dist/data-source.test.d.ts.map +1 -0
  27. package/dist/debug-leash.d.ts +73 -0
  28. package/dist/debug-leash.d.ts.map +1 -0
  29. package/dist/export.d.ts +69 -0
  30. package/dist/export.d.ts.map +1 -0
  31. package/dist/export.test.d.ts +2 -0
  32. package/dist/export.test.d.ts.map +1 -0
  33. package/dist/feature-id-hash.d.ts +26 -0
  34. package/dist/feature-id-hash.d.ts.map +1 -0
  35. package/dist/feature-id-hash.test.d.ts +2 -0
  36. package/dist/feature-id-hash.test.d.ts.map +1 -0
  37. package/dist/figure-scale.d.ts +145 -0
  38. package/dist/figure-scale.d.ts.map +1 -0
  39. package/dist/figure-scale.test.d.ts +2 -0
  40. package/dist/figure-scale.test.d.ts.map +1 -0
  41. package/dist/gutter.test.d.ts +2 -0
  42. package/dist/gutter.test.d.ts.map +1 -0
  43. package/dist/index.d.ts +62 -0
  44. package/dist/index.d.ts.map +1 -0
  45. package/dist/index.js +7910 -0
  46. package/dist/index.js.map +1 -0
  47. package/dist/layout-engine.d.ts +52 -0
  48. package/dist/layout-engine.d.ts.map +1 -0
  49. package/dist/layout-engine.test.d.ts +2 -0
  50. package/dist/layout-engine.test.d.ts.map +1 -0
  51. package/dist/pack-lanes.d.ts +27 -0
  52. package/dist/pack-lanes.d.ts.map +1 -0
  53. package/dist/pack-lanes.test.d.ts +2 -0
  54. package/dist/pack-lanes.test.d.ts.map +1 -0
  55. package/dist/painter/index.d.ts +4 -0
  56. package/dist/painter/index.d.ts.map +1 -0
  57. package/dist/painter/svg-painter.d.ts +6 -0
  58. package/dist/painter/svg-painter.d.ts.map +1 -0
  59. package/dist/painter/svg-painter.test.d.ts +2 -0
  60. package/dist/painter/svg-painter.test.d.ts.map +1 -0
  61. package/dist/projection-frame.d.ts +92 -0
  62. package/dist/projection-frame.d.ts.map +1 -0
  63. package/dist/projection-frame.test.d.ts +2 -0
  64. package/dist/projection-frame.test.d.ts.map +1 -0
  65. package/dist/segments.d.ts +86 -0
  66. package/dist/segments.d.ts.map +1 -0
  67. package/dist/slots.test.d.ts +2 -0
  68. package/dist/slots.test.d.ts.map +1 -0
  69. package/dist/styles.css +1127 -0
  70. package/dist/symbol-encoding.d.ts +103 -0
  71. package/dist/symbol-encoding.d.ts.map +1 -0
  72. package/dist/symbol-encoding.test.d.ts +2 -0
  73. package/dist/symbol-encoding.test.d.ts.map +1 -0
  74. package/dist/test-setup.d.ts +2 -0
  75. package/dist/test-setup.d.ts.map +1 -0
  76. package/dist/tracks/aa-track.d.ts +67 -0
  77. package/dist/tracks/aa-track.d.ts.map +1 -0
  78. package/dist/tracks/aa-track.test.d.ts +2 -0
  79. package/dist/tracks/aa-track.test.d.ts.map +1 -0
  80. package/dist/tracks/clinvar-summary-track.d.ts +29 -0
  81. package/dist/tracks/clinvar-summary-track.d.ts.map +1 -0
  82. package/dist/tracks/clinvar-summary-track.test.d.ts +2 -0
  83. package/dist/tracks/clinvar-summary-track.test.d.ts.map +1 -0
  84. package/dist/tracks/clinvar-track.d.ts +161 -0
  85. package/dist/tracks/clinvar-track.d.ts.map +1 -0
  86. package/dist/tracks/clinvar-track.test.d.ts +2 -0
  87. package/dist/tracks/clinvar-track.test.d.ts.map +1 -0
  88. package/dist/tracks/exon-track.d.ts +25 -0
  89. package/dist/tracks/exon-track.d.ts.map +1 -0
  90. package/dist/tracks/exon-track.test.d.ts +2 -0
  91. package/dist/tracks/exon-track.test.d.ts.map +1 -0
  92. package/dist/tracks/interpro-track.d.ts +69 -0
  93. package/dist/tracks/interpro-track.d.ts.map +1 -0
  94. package/dist/tracks/interpro-track.test.d.ts +2 -0
  95. package/dist/tracks/interpro-track.test.d.ts.map +1 -0
  96. package/dist/tracks/nucleotide-track.d.ts +84 -0
  97. package/dist/tracks/nucleotide-track.d.ts.map +1 -0
  98. package/dist/tracks/nucleotide-track.test.d.ts +2 -0
  99. package/dist/tracks/nucleotide-track.test.d.ts.map +1 -0
  100. package/dist/tracks/overview-track.d.ts +50 -0
  101. package/dist/tracks/overview-track.d.ts.map +1 -0
  102. package/dist/tracks/overview-track.test.d.ts +2 -0
  103. package/dist/tracks/overview-track.test.d.ts.map +1 -0
  104. package/dist/tracks/parse-user-variants.d.ts +55 -0
  105. package/dist/tracks/parse-user-variants.d.ts.map +1 -0
  106. package/dist/tracks/parse-user-variants.test.d.ts +2 -0
  107. package/dist/tracks/parse-user-variants.test.d.ts.map +1 -0
  108. package/dist/tracks/pfam-track.d.ts +33 -0
  109. package/dist/tracks/pfam-track.d.ts.map +1 -0
  110. package/dist/tracks/pfam-track.test.d.ts +2 -0
  111. package/dist/tracks/pfam-track.test.d.ts.map +1 -0
  112. package/dist/tracks/profile-track.d.ts +133 -0
  113. package/dist/tracks/profile-track.d.ts.map +1 -0
  114. package/dist/tracks/profile-track.test.d.ts +2 -0
  115. package/dist/tracks/profile-track.test.d.ts.map +1 -0
  116. package/dist/tracks/scale-track.d.ts +70 -0
  117. package/dist/tracks/scale-track.d.ts.map +1 -0
  118. package/dist/tracks/scale-track.test.d.ts +2 -0
  119. package/dist/tracks/scale-track.test.d.ts.map +1 -0
  120. package/dist/tracks/segment-band-track.d.ts +86 -0
  121. package/dist/tracks/segment-band-track.d.ts.map +1 -0
  122. package/dist/tracks/segment-band-track.test.d.ts +2 -0
  123. package/dist/tracks/segment-band-track.test.d.ts.map +1 -0
  124. package/dist/tracks/user-variant-track.d.ts +50 -0
  125. package/dist/tracks/user-variant-track.d.ts.map +1 -0
  126. package/dist/tracks/user-variant-track.test.d.ts +2 -0
  127. package/dist/tracks/user-variant-track.test.d.ts.map +1 -0
  128. package/dist/tracks/variant-summary-track.d.ts +24 -0
  129. package/dist/tracks/variant-summary-track.d.ts.map +1 -0
  130. package/dist/tracks/variant-summary-track.test.d.ts +2 -0
  131. package/dist/tracks/variant-summary-track.test.d.ts.map +1 -0
  132. package/dist/tracks/variant-track.d.ts +89 -0
  133. package/dist/tracks/variant-track.d.ts.map +1 -0
  134. package/dist/tracks/variant-track.test.d.ts +2 -0
  135. package/dist/tracks/variant-track.test.d.ts.map +1 -0
  136. package/dist/types.d.ts +671 -0
  137. package/dist/types.d.ts.map +1 -0
  138. package/dist/use-viewport-interactions.d.ts +49 -0
  139. package/dist/use-viewport-interactions.d.ts.map +1 -0
  140. package/dist/viewer-interactions.test.d.ts +2 -0
  141. package/dist/viewer-interactions.test.d.ts.map +1 -0
  142. package/dist/viewer-overlay.test.d.ts +2 -0
  143. package/dist/viewer-overlay.test.d.ts.map +1 -0
  144. package/dist/viewer-selection-range.test.d.ts +2 -0
  145. package/dist/viewer-selection-range.test.d.ts.map +1 -0
  146. package/dist/viewer.d.ts +319 -0
  147. package/dist/viewer.d.ts.map +1 -0
  148. package/dist/viewer.test.d.ts +2 -0
  149. package/dist/viewer.test.d.ts.map +1 -0
  150. package/dist/viewport.d.ts +352 -0
  151. package/dist/viewport.d.ts.map +1 -0
  152. package/dist/viewport.test.d.ts +2 -0
  153. package/dist/viewport.test.d.ts.map +1 -0
  154. package/package.json +65 -4
@@ -0,0 +1,671 @@
1
+ import type { ReactNode } from 'react';
2
+ export interface Exon {
3
+ number: number;
4
+ cdsStart: number;
5
+ cdsEnd: number;
6
+ genomicStart: number;
7
+ genomicEnd: number;
8
+ chr: string;
9
+ /** 5' UTR length (bp) within this exon — typically non-zero only on the
10
+ * first CDS-containing exon. Optional; defaults to 0. The viewport
11
+ * allocates display width for UTR bp at the same `pxPerBp` as CDS bp,
12
+ * visually compressing the CDS to make room. */
13
+ utr5Bp?: number;
14
+ /** 3' UTR length (bp) within this exon — typically non-zero only on the
15
+ * last CDS-containing exon. */
16
+ utr3Bp?: number;
17
+ }
18
+ export interface Transcript {
19
+ geneSymbol: string;
20
+ transcriptId: string;
21
+ isManeSelect?: boolean;
22
+ cdsLength: number;
23
+ strand: '+' | '-';
24
+ exons: Exon[];
25
+ }
26
+ export type ProteinDomainEntryType = 'domain' | 'family' | 'repeat' | 'homologous_superfamily' | 'conserved_site' | 'active_site' | 'binding_site' | 'ptm' | 'unspecified';
27
+ export interface ProteinDomain {
28
+ aaStart: number;
29
+ aaEnd: number;
30
+ source: string;
31
+ sourceId: string;
32
+ shortName: string;
33
+ description: string;
34
+ entryType: ProteinDomainEntryType;
35
+ }
36
+ export interface ProteinAnnotations {
37
+ uniprotAcc: string;
38
+ length: number;
39
+ alphafoldId?: string;
40
+ domains: ProteinDomain[];
41
+ }
42
+ export type VariantCategory = 'missense' | 'nonsense' | 'synonymous' | 'frameshift' | 'inframe_indel' | 'splice' | 'start_lost' | 'stop_lost' | 'regulatory' | 'utr' | 'intronic' | 'structural' | 'other' | 'unknown';
43
+ /** A position in one of the three biological coordinate systems. The
44
+ * tagged union lets callers hand any-coord-typed data straight to the
45
+ * viewport's projection methods without a `(viewport.mode, coordSystem)`
46
+ * branch on the caller side — the dispatch happens once inside
47
+ * {@link Viewport.toScreen} / {@link Viewport.toBaselineX}, not at every
48
+ * callsite that needs to place a feature. */
49
+ export type Position = {
50
+ kind: 'cds';
51
+ cPos: number;
52
+ offset: number;
53
+ } | {
54
+ kind: 'protein';
55
+ aa: number;
56
+ } | {
57
+ kind: 'genomic';
58
+ chr: string;
59
+ pos: number;
60
+ };
61
+ /** Coord payload carried by ViewerVariant. Same shape as {@link Position}
62
+ * by design — host data adapters produce variants in any coord system,
63
+ * and tracks hand them straight to the viewport without translation. */
64
+ export type VariantCoord = Position;
65
+ export interface ViewerVariant {
66
+ id: string;
67
+ label: string;
68
+ coord: VariantCoord;
69
+ category: VariantCategory;
70
+ /** Raw VEP / SO consequence term (e.g. `splice_donor_variant`,
71
+ * `missense_variant`). Optional. The 14-value {@link VariantCategory}
72
+ * coarsens VEP's vocabulary in ways that lose distinctions some
73
+ * encodings need (LOF-splice vs splice-region both collapse to
74
+ * `splice`); carrying the raw term lets downstream encodings make
75
+ * fine-grained colour / shape choices without enum churn. */
76
+ consequence?: string;
77
+ meta?: Record<string, unknown>;
78
+ }
79
+ export interface ViewportQuery {
80
+ mode: ViewMode;
81
+ range: readonly [number, number];
82
+ }
83
+ export type DataSourceFreshness = 'on-viewport-change' | 'sticky' | 'realtime';
84
+ export interface DataSource<TQuery, TResult> {
85
+ readonly id: string;
86
+ cacheKey(query: TQuery): string;
87
+ query(query: TQuery, signal: AbortSignal): Promise<TResult>;
88
+ freshness?: DataSourceFreshness;
89
+ }
90
+ export declare function isDataSource<TQuery, TResult>(value: unknown): value is DataSource<TQuery, TResult>;
91
+ /** Per-track load lifecycle reported via `onTrackStateChange`. Hosts use this
92
+ * to drive their own loading UI or telemetry. The viewer renders a default
93
+ * shimmer affordance over the track's y-range while `state === 'loading'`,
94
+ * and desaturates feature fills via `[data-vv-stale]` during the
95
+ * pre-`track.load` debounce window. Slice 18. */
96
+ export type TrackLoadState = 'loading' | 'ready' | 'error';
97
+ export type ViewMode = 'genome' | 'transcript' | 'protein';
98
+ /** Default-binding profile applied to user gestures on the figure. `standard`
99
+ * enables drag-pan, wheel-pan, Cmd/Ctrl+wheel-zoom, pinch-zoom, and keyboard;
100
+ * `embed` is the same set minus wheel-zoom (so the viewer doesn't fight a
101
+ * scrolling host page); `fullscreen` is the same as `standard` for now and
102
+ * exists as a hook for later (e.g. modal viewers that opt into wheel-zoom
103
+ * without modifiers). */
104
+ export type InteractionMode = 'standard' | 'embed' | 'fullscreen';
105
+ /** Tag passed to `onViewportChange` so hosts can distinguish user gestures
106
+ * from programmatic updates (e.g. for telemetry or undo stacks). */
107
+ export type ViewportChangeReason = 'drag' | 'wheel' | 'wheel-zoom' | 'pinch' | 'keyboard' | 'imperative' | 'box-zoom';
108
+ export type CoordSystem = 'genomic' | 'cds' | 'protein';
109
+ export interface CdsPosition {
110
+ cPos: number;
111
+ offset: number;
112
+ }
113
+ /** A region of the gene marked for *soft* (display-only) collapse. The
114
+ * endpoints are given in HGVS c. coordinates — `cPos` is the bracketing
115
+ * exonic CDS bp, and `offset` is the intronic offset (`+N` past an exon's
116
+ * 3' end, `-N` before an exon's 5' end; `0` for exonic positions). Soft
117
+ * collapse renders the named range at a fixed pixel budget while leaving
118
+ * the surrounding linear regions to scale with zoom — that's what
119
+ * produces the splice-site-aware genome view.
120
+ *
121
+ * Spec semantics:
122
+ * - In `genome` mode, every region in the spec becomes a fixed-budget
123
+ * intron-bulk segment. Linear flanks around it (the bp between an
124
+ * exon edge and the spec's nearest collapse boundary) scale with zoom.
125
+ * - In `transcript` / `protein` modes, intronic spec entries are
126
+ * subsumed by the mode's hard collapse and don't affect rendering.
127
+ * - Endpoints are inclusive: `start` is the first compressed bp,
128
+ * `end` is the last. */
129
+ export interface CollapsedRegion {
130
+ start: CdsPosition;
131
+ end: CdsPosition;
132
+ }
133
+ export interface GenomicPosition {
134
+ chr: string;
135
+ pos: number;
136
+ }
137
+ export interface RangeSegment {
138
+ xStart: number;
139
+ xEnd: number;
140
+ exonIdx: number;
141
+ }
142
+ /** Description of one range fragment that the projection couldn't render in
143
+ * the visible-exon frame. `intronic` carries the bracketing exon pair so a
144
+ * track that aggregates hidden-feature counts (Slice 15) can index by intron
145
+ * gap; `out-of-bounds` carries no extra detail. */
146
+ export type DroppedRange = {
147
+ kind: 'intronic';
148
+ exonIdxA: number;
149
+ exonIdxB: number;
150
+ } | {
151
+ kind: 'out-of-bounds';
152
+ };
153
+ export interface RangeProjection {
154
+ segments: RangeSegment[];
155
+ droppedIntronicCount: number;
156
+ droppedExonicCount: number;
157
+ droppedRanges: DroppedRange[];
158
+ }
159
+ /** Hidden-feature count contributed by one track for one intron gap (Slice
160
+ * 15). The viewer sums these across tracks and surfaces the totals to the
161
+ * exon track as `TrackRenderArgs.hiddenByIntron` so the exon track can render
162
+ * a single count badge per gap. `featureIds` is optional metadata for hosts
163
+ * that want to drive a popover from the click callback. */
164
+ export interface HiddenFeatureBucket {
165
+ exonIdxA: number;
166
+ exonIdxB: number;
167
+ count: number;
168
+ featureIds?: string[];
169
+ }
170
+ export type AnchorTarget = {
171
+ kind: 'feature';
172
+ trackId: string;
173
+ featureId: string;
174
+ } | {
175
+ kind: 'intron-boundary';
176
+ exonIdx: number;
177
+ side: 'donor' | 'acceptor';
178
+ } | {
179
+ kind: 'protein-aa';
180
+ aa: number;
181
+ } | {
182
+ kind: 'cds-pos';
183
+ cPos: number;
184
+ offset?: number;
185
+ } | {
186
+ kind: 'genomic-pos';
187
+ chr: string;
188
+ pos: number;
189
+ };
190
+ export interface ScreenPoint {
191
+ x: number;
192
+ y: number;
193
+ }
194
+ /** Args passed to {@link GeneGlyphProps.renderTooltip}. Slice 17 ships hover
195
+ * tooltips as the first overlay kind; future overlay anchors (intron
196
+ * boundaries, "you are here" markers) reuse the same `point` contract. */
197
+ export interface TooltipRenderArgs {
198
+ trackId: string;
199
+ featureId: string;
200
+ /** Track-specific feature payload, resolved via
201
+ * {@link Track.resolveFeature}. `undefined` when the track does not
202
+ * implement the hook. */
203
+ feature: unknown;
204
+ /** Anchor position in figure-SVG viewBox units; viewer converts to client
205
+ * pixels for overlay placement. Hosts rarely need this — included for
206
+ * symmetry with imperative overlay APIs landing in later slices. */
207
+ point: ScreenPoint;
208
+ }
209
+ export interface CoordinateMapper {
210
+ readonly transcript: Transcript;
211
+ genomicToCds(chr: string, pos: number): CdsPosition | null;
212
+ cdsToGenomic(cPos: number, offset: number): GenomicPosition | null;
213
+ cdsToProtein(cPos: number): number | null;
214
+ proteinToCds(aa: number): number;
215
+ findExonByCds(cPos: number): {
216
+ exonIdx: number;
217
+ } | null;
218
+ findExonByGenomic(chr: string, pos: number): {
219
+ exonIdx: number;
220
+ } | null;
221
+ /** Reduce a {@link Position} (any coord system) to a CDS `(cPos, offset)`
222
+ * pair. Returns `null` for genomic positions that don't land on the
223
+ * transcript. Lets callers stop hand-rolling the same
224
+ * `switch (coord.kind)` reduction at every site that needs a unified
225
+ * CDS view of a tagged coord. */
226
+ resolveCds(pos: Position): CdsPosition | null;
227
+ }
228
+ /** Per-exon rectangle in baseline screen-x. Exposed to tracks via
229
+ * {@link Viewport.baselineGeometry}; tracks render features against this
230
+ * frame so React never reissues SVG attribute widths on pan or zoom — only
231
+ * the wrapping `<g>` transforms change, and CSS transitions those. */
232
+ export interface ExonBaseline {
233
+ exonIdx: number;
234
+ /** Baseline x of the CDS portion's left edge (within the exon's display
235
+ * rect — see `utr5Px` for the UTR cap that sits to the left of this). */
236
+ xStart: number;
237
+ /** Baseline x of the CDS portion's right edge. */
238
+ xEnd: number;
239
+ /** CDS-portion width: `xEnd - xStart`. */
240
+ width: number;
241
+ /** Display width allocated to this exon's 5' UTR (bp × pxPerBp). The
242
+ * cap sits at `[xStart - utr5Px, xStart]`. Zero when the exon has no
243
+ * 5' UTR (the common case for everything but the first exon). */
244
+ utr5Px?: number;
245
+ /** Display width allocated to this exon's 3' UTR. The cap sits at
246
+ * `[xEnd, xEnd + utr3Px]`. */
247
+ utr3Px?: number;
248
+ }
249
+ export interface GapBaseline {
250
+ exonIdxA: number;
251
+ exonIdxB: number;
252
+ xStart: number;
253
+ xEnd: number;
254
+ width: number;
255
+ /** Phase 3: scale behaviour of this gap under zoom. `'fixed-budget'`
256
+ * means the gap stays at its baseline pixel width regardless of
257
+ * zoom (the soft-collapsed bulk-intron case). `'linear'` means it
258
+ * scales with the surrounding exon content (transcript mode's 1bp
259
+ * transition; protein mode's zero-width gap). Optional for
260
+ * backwards compat — buildSegments falls back to inferring from
261
+ * the global `gapPx` when unset. */
262
+ scaleRule?: 'linear' | 'fixed-budget';
263
+ }
264
+ /** Phase 3: per-intron flank piece — the linear-scale region of an
265
+ * intron immediately adjacent to its bracketing exons. Donor flanks
266
+ * sit on the upstream-exon side of the intron (5' end); acceptor
267
+ * flanks on the downstream-exon side (3' end). Each flank carries
268
+ * the bp count it covers so {@link buildSegments} can map ruler
269
+ * positions through it. */
270
+ export interface FlankBaseline {
271
+ intronIdx: number;
272
+ side: 'donor' | 'acceptor';
273
+ bp: number;
274
+ xStart: number;
275
+ xEnd: number;
276
+ width: number;
277
+ }
278
+ export interface BaselineGeometry {
279
+ exons: ExonBaseline[];
280
+ gaps: GapBaseline[];
281
+ /** Phase 3: per-intron linear-scale flank pieces. Empty (or
282
+ * undefined) when no soft-collapse spec is in effect. In genome
283
+ * mode with the default spec, each intron contributes a donor and
284
+ * acceptor flank so the 10bp splice-site sequence scales with the
285
+ * surrounding exon content while the bulk between them stays at a
286
+ * fixed pixel budget. */
287
+ flanks?: FlankBaseline[];
288
+ flanksByIntron?: Map<number, {
289
+ donor: number;
290
+ acceptor: number;
291
+ }>;
292
+ pxPerBp: number;
293
+ /** Rate used when projecting ruler positions outside the first/last
294
+ * exon segment (e.g., UTR coordinates). In CDS modes this is
295
+ * `pxPerBp × UTR_DISPLAY_SCALE` so each UTR bp consumes a fraction
296
+ * of the display a CDS bp does, reflecting that UTRs are visual
297
+ * context rather than the protein-coding payload. Equal to `pxPerBp`
298
+ * in protein mode (no UTRs in aa space). */
299
+ pxPerBpOutsideCds: number;
300
+ gapPx: number;
301
+ totalWidth: number;
302
+ }
303
+ export interface Viewport {
304
+ readonly mode: ViewMode;
305
+ readonly intronScale: number;
306
+ /** Visible ruler range. Derived from {@link baselineWindow} via the
307
+ * segment walk — round-trip-exact for windows whose endpoints sit in
308
+ * exonic regions; snaps to the nearest cell-boundary when an endpoint
309
+ * sits inside a fixed-budget gap (where the synthetic ruler has zero
310
+ * span and the inverse is ambiguous). */
311
+ readonly range: readonly [number, number];
312
+ readonly width: number;
313
+ /** Natural fit-gene ruler range for the active mode. CDS bp in CDS
314
+ * modes, aa in protein mode. Stable until the mode or transcript
315
+ * changes; chrome / minimap code uses it as the thumbnail span. */
316
+ naturalRange(): readonly [number, number];
317
+ /** Canonical viewport state in display (baseline) coordinates: `[S_lo,
318
+ * S_hi]` in fit-gene baseline-x. The figure renders this slice of the
319
+ * baseline to current-x `[0, width]`. Pan / zoom operate on this state
320
+ * directly so the gesture math doesn't round-trip through the ruler. */
321
+ baselineWindow(): readonly [number, number];
322
+ /** Project a {@link Position} (any coord system) onto current screen-x.
323
+ * Returns `null` when the position can't be placed in the active mode
324
+ * — intronic offsets, genomic positions outside any exon, or positions
325
+ * panned out of the current viewport. The single entry point replaces
326
+ * the three-door `cdsToScreen` / `proteinToScreen` / `genomicToScreen`
327
+ * trio for callers that carry tagged coords. */
328
+ toScreen(pos: Position): number | null;
329
+ /** Project a {@link Position} onto fit-gene baseline-x. Same null
330
+ * contract as {@link toScreen}, but never returns null because of
331
+ * out-of-viewport — only for unplaceable coords (intronic offsets,
332
+ * off-transcript genomic positions). Tracks rendering against the
333
+ * baseline-x frame use this to anchor features. */
334
+ toBaselineX(pos: Position): number | null;
335
+ cdsToScreen(cPos: number, offset: number): number | null;
336
+ proteinToScreen(aa: number): number | null;
337
+ genomicToScreen(chr: string, pos: number): number | null;
338
+ /** Project a current screen-x back into a {@link Position} of the
339
+ * requested coord system. Inverse of {@link toScreen}; the two paths
340
+ * share the same ruler conversion so the round-trip can't diverge.
341
+ * Returns `null` for off-figure x or unresolvable positions. The
342
+ * return type narrows to the requested kind so callers don't have
343
+ * to re-check `.kind`. */
344
+ screenToPosition<K extends 'cds' | 'protein' | 'genomic'>(x: number, kind: K): Extract<Position, {
345
+ kind: K;
346
+ }> | null;
347
+ screenToCds(x: number): CdsPosition | null;
348
+ screenToProtein(x: number): number | null;
349
+ screenToGenomic(x: number): GenomicPosition | null;
350
+ /** Ruler → baseline screen-x. CDS bp in CDS modes, aa in protein mode.
351
+ * Always returns a finite value (extrapolates past the gene's edges). */
352
+ cdsToBaselineX(rulerPos: number): number;
353
+ /** Baseline screen-x → current-zoom layout-x (the figure's static
354
+ * layout coordinate, including soft-collapse but excluding the live
355
+ * pan offset's effect on relative positions). Tracks doing zoom-
356
+ * responsive packing (e.g. stacked ClinVar) use this so the row
357
+ * count tracks the actual on-figure spread of glyphs. */
358
+ baselineToLayoutX(baselineX: number): number;
359
+ /** Inverse of {@link cdsToBaselineX}. CDS bp in CDS modes, aa in protein
360
+ * mode. Fractional; callers round if they want a discrete ruler value.
361
+ * Slice 26 surfaced this on the public interface so direct-manipulation
362
+ * chrome embedded as a track (overviewTrack) can map cursor positions
363
+ * back to ruler coords without reaching for the controller subclass. */
364
+ baselineXToRuler(x: number): number;
365
+ /** Live screen-x → baseline screen-x. The figure renders exons via per-
366
+ * exon CSS transforms that aren't a uniform scale (inter-exon gaps stay
367
+ * at their baseline pixel width regardless of zoom — see the publish
368
+ * comment in {@link ViewportController.publish}); the live-to-baseline
369
+ * mapping therefore isn't just `(currentX / zoom + S_lo)`. Slice 26
370
+ * exposes this on the public interface so the overview track can mark
371
+ * the *actually-visible* baseline range, including past-the-gene-end
372
+ * padding zones. Extrapolates linearly past the last exon. */
373
+ screenToBaselineX(currentX: number): number;
374
+ /** Live scale factor applied to exon-body baseline pixels — the screen
375
+ * width that 1 baseline-px of exon takes at the current zoom. In modes
376
+ * without fixed-budget elements this is `width / visibleBaselineSpan`.
377
+ * In genome mode it diverges from the screen-space `zoomFactor()` when
378
+ * the visible window contains any fixed-budget gap budget: gap pixels
379
+ * stay at their fixed budget, so exon content scales up to consume the
380
+ * remaining screen pixels. Pan / wheel-pan use this to make 1 viewbox-
381
+ * px of drag move exon content by exactly 1 px on screen (gap content
382
+ * shifts at 1:1 baseline = `1/exonScale` of a screen-px, lagging
383
+ * slightly — the intentional consequence of the fixed-budget design). */
384
+ exonScale(): number;
385
+ /** Local screen-to-baseline scale at a given current-x — the screen
386
+ * width that 1 baseline-px takes at this *specific* point on the
387
+ * figure. In modes with a uniform mapping this equals `exonScale()`
388
+ * everywhere; in `genome` mode it returns the exon scale inside
389
+ * exon segments, 1 inside a fixed-budget gap bulk, and the padding
390
+ * scale in the 5'/3' padding zone. Pan uses this to make a Δviewbox
391
+ * drag move the baseline UNDER THE CURSOR by exactly Δviewbox
392
+ * pixels — so whatever the user grabs stays under their pointer. */
393
+ localScreenScaleAt(currentX: number): number;
394
+ /** Viewport-independent geometry at fit-gene zoom. Tracks render against
395
+ * this frame; the wrapping exon/intron `<g>` elements carry the live
396
+ * translate + scale derived from the current range. */
397
+ baselineGeometry(): BaselineGeometry;
398
+ projectCdsRange(start: number, end: number): RangeProjection;
399
+ projectProteinRange(aaStart: number, aaEnd: number): RangeProjection;
400
+ projectGenomicRange(chr: string, start: number, end: number): RangeProjection;
401
+ resolveAnchor(target: AnchorTarget): ScreenPoint | null;
402
+ }
403
+ export type HeightPolicy = 'fixed' | 'data-dependent' | 'zoom-dependent';
404
+ export interface TrackRect {
405
+ yTop: number;
406
+ yBottom: number;
407
+ }
408
+ export interface TrackHeightHint {
409
+ maxPx: number;
410
+ }
411
+ /** Baseline-x extent of a feature's reference span. Used by the
412
+ * selection-range overlay (Slice 35). `anchorX === farX` for SNVs;
413
+ * multi-bp variants report the two ends. Coordinates ride the same
414
+ * per-exon CSS transform that placed the feature, so the viewer can
415
+ * map them to layout-x with {@link Viewport.baselineToLayoutX}. */
416
+ export interface FeatureRange {
417
+ anchorX: number;
418
+ farX: number;
419
+ }
420
+ export interface TrackHeightResult {
421
+ px: number;
422
+ didTruncate: boolean;
423
+ droppedCount?: number;
424
+ }
425
+ export interface InteractionState {
426
+ hoveredFeatureId: string | null;
427
+ selectedFeatureIds: ReadonlySet<string>;
428
+ brushRange: readonly [number, number] | null;
429
+ }
430
+ export interface TrackLoadArgs {
431
+ viewport: Viewport;
432
+ mapper: CoordinateMapper;
433
+ signal: AbortSignal;
434
+ /** ProteinAnnotations passed to `<GeneGlyph>` as the `protein` prop, or
435
+ * `null` when the host didn't provide one. Protein-coord tracks (Pfam,
436
+ * InterPro, AlphaMissense, MAVE) read their data from here instead of
437
+ * taking it as track config — the host already knows where the protein
438
+ * record lives for the chosen transcript, so requiring tracks to
439
+ * redeclare it would be ceremony without payoff. */
440
+ protein: ProteinAnnotations | null;
441
+ }
442
+ export interface TrackHeightArgs<TData> {
443
+ data: TData | null;
444
+ viewport: Viewport;
445
+ hint: TrackHeightHint;
446
+ }
447
+ /** Args passed to {@link Track.renderMinimap}. The minimap is a pure
448
+ * display-space artifact: the track is handed a target width and height
449
+ * in pixels and asked to render its content at fit-gene scale, decoupled
450
+ * from the figure's live zoom / pan / CSS-variable transforms. Tracks
451
+ * that have no meaningful thumbnail (overlay-only tracks, the overview
452
+ * track itself) omit the hook and the host minimap skips them. Slice 26. */
453
+ export interface MinimapRenderArgs<TData> {
454
+ data: TData;
455
+ /** Target width in viewBox pixels. The track should fill `[0, width]`
456
+ * on the x axis. */
457
+ width: number;
458
+ /** Target height in viewBox pixels. The track should fill `[0, height]`
459
+ * on the y axis. */
460
+ height: number;
461
+ /** Pre-built mini-viewport at the target width, pinned to fit-gene zoom
462
+ * in the current mode. Tracks can use its `baselineGeometry()` to read
463
+ * per-exon screen positions and widths without recomputing them. */
464
+ viewport: Viewport;
465
+ mapper: CoordinateMapper;
466
+ painter: Painter;
467
+ }
468
+ export interface TrackRenderArgs<TData> {
469
+ data: TData;
470
+ rect: TrackRect;
471
+ viewport: Viewport;
472
+ mapper: CoordinateMapper;
473
+ interaction: InteractionState;
474
+ painter: Painter;
475
+ /** Per-intron-gap counts of features hidden by the current viewport. The
476
+ * viewer aggregates {@link Track.hiddenFeaturesByIntron} across every track
477
+ * and passes the totals here so a single track (the exon track by default)
478
+ * can render one indicator per gap rather than each track stacking its own.
479
+ * Keys are `${exonIdxA}:${exonIdxB}`. Optional so tests can construct
480
+ * render-args without a viewer; production renders always receive a map
481
+ * (empty when no track contributes). */
482
+ hiddenByIntron?: ReadonlyMap<string, HiddenFeatureBucket>;
483
+ /** Fires when the cursor enters or leaves a feature in this track; pass
484
+ * `null` for leave. Tracks wire this onto the per-feature `<g>` they
485
+ * render. The viewer maps it onto the host's `onHover` prop. */
486
+ onFeatureHover?: (featureId: string | null) => void;
487
+ /** Fires when a feature in this track is clicked. The viewer maps it onto
488
+ * the host's `onFeatureClick` prop. */
489
+ onFeatureClick?: (featureId: string) => void;
490
+ }
491
+ export interface HiddenFeaturesArgs<TData> {
492
+ data: TData;
493
+ viewport: Viewport;
494
+ mapper: CoordinateMapper;
495
+ }
496
+ export interface Track<TConfig = unknown, TData = unknown> {
497
+ readonly id: string;
498
+ /** Opt-in re-load key. When supplied, the viewer folds this string into
499
+ * its per-track identity, so a change (e.g. a host filter that
500
+ * reshapes the laid-out data) forces `load()` to re-run and `height()`
501
+ * to recompute. Leave undefined when the track's config never
502
+ * affects layout post-construction — the default identity is the
503
+ * track id alone. */
504
+ readonly configKey?: string;
505
+ /** Optional human-readable label surfaced to gutter render-props via the
506
+ * {@link GutterItem} for this track. When a track sits inside a
507
+ * {@link TrackGroup} (e.g. the entry-type sub-tracks emitted by
508
+ * `interProTrack`), the label conveys the sub-track's category so a
509
+ * multi-level gutter can render the nesting structure. Hosts can render
510
+ * the label however they like — italic small-caps for entry-types,
511
+ * bold for primary tracks — by branching on `kind` / `item.id` in the
512
+ * render-prop. */
513
+ readonly label?: string;
514
+ readonly coordSystem: CoordSystem;
515
+ readonly heightPolicy: HeightPolicy;
516
+ /** Vertical pixels reserved above this track during layout. Mirrors
517
+ * {@link TrackGroup.gapAbove} for leaf tracks — useful when two
518
+ * adjacent tracks would otherwise visually merge at their shared
519
+ * edge (e.g. a histogram whose tallest bars touch the heatmap above
520
+ * it). Default 0 (flush layout). */
521
+ readonly gapAbove?: number;
522
+ load(args: TrackLoadArgs): Promise<TData>;
523
+ height(args: TrackHeightArgs<TData>): TrackHeightResult;
524
+ /** Per-intron-gap hidden-feature counts contributed by this track. The
525
+ * viewer aggregates these across tracks and exposes the totals via
526
+ * {@link TrackRenderArgs.hiddenByIntron}; tracks that don't drop features
527
+ * in collapsed introns can omit this. */
528
+ hiddenFeaturesByIntron?(args: HiddenFeaturesArgs<TData>): HiddenFeatureBucket[];
529
+ render(args: TrackRenderArgs<TData>): ReactNode;
530
+ /** Optional minimap representation of this track at a fixed pixel size,
531
+ * decoupled from the figure's live viewport. The overview track (and
532
+ * any host-supplied minimap chrome) invokes this to compose a
533
+ * display-space thumbnail of the track stack — exons appear at
534
+ * fit-gene baseline, features (variants, domains, etc.) at the same
535
+ * scale. Tracks that don't have a useful thumbnail (the overview track
536
+ * itself, overlay-only tracks) omit this hook. Slice 26. */
537
+ renderMinimap?(args: MinimapRenderArgs<TData>): ReactNode | null;
538
+ /** Optional DOM rendered below the figure SVG (e.g., unplaced-feature
539
+ * lists). Lives in a sibling `<div class="vv-below">` outside the figure
540
+ * so it never leaks into export. Slice 7 introduces formal slots; this
541
+ * hook keeps the below-figure surface simple until then. */
542
+ renderBelow?(args: TrackRenderArgs<TData>): ReactNode | null;
543
+ resolveAnchor?(data: TData, anchorId: string, viewport: Viewport): ScreenPoint | null;
544
+ /** Resolve the baseline-x extent of a selected feature for the
545
+ * selection-range overlay (Slice 35). Returns the two ends of the
546
+ * feature's reference span in baseline-x. For SNVs `anchorX ===
547
+ * farX` and the viewer falls back to a single vertical drop-line;
548
+ * multi-bp variants render as a translucent rect spanning the two
549
+ * ends. Tracks that don't carry coordinate-anchored features (e.g.
550
+ * the scale ruler) omit this. */
551
+ resolveFeatureRange?(data: TData, featureId: string, viewport: Viewport, mapper: CoordinateMapper): FeatureRange | null;
552
+ /** Resolve the track-specific feature object for `featureId`. The viewer
553
+ * passes the returned value to host-supplied
554
+ * {@link GeneGlyphProps.renderTooltip} so hosts can render rich tooltips
555
+ * without re-resolving from their own data. Slice 17. */
556
+ resolveFeature?(data: TData, featureId: string): unknown;
557
+ /** Short label for the viewer's built-in tooltip. Used when the host has
558
+ * not supplied {@link GeneGlyphProps.renderTooltip}. Returning `null`
559
+ * (or omitting the hook) suppresses the default tooltip. Slice 17. */
560
+ featureLabel?(data: TData, featureId: string): string | null;
561
+ toJSON(): TConfig;
562
+ }
563
+ export interface TrackGroup {
564
+ kind: 'group';
565
+ id: string;
566
+ label: string;
567
+ defaultExpanded?: boolean;
568
+ gapAbove?: number;
569
+ heightBudget?: number;
570
+ /** Group members. Each entry is either a leaf {@link Track} or a nested
571
+ * {@link TrackGroup}; nesting is unbounded, so the standard pattern
572
+ * "parent group containing per-bucket sub-groups, each with its own
573
+ * detail + summary" is expressible without flattening the structure
574
+ * at the host. The layout engine recurses through nested groups and
575
+ * consults the same `collapsedGroupIds` set at every level. */
576
+ tracks: TrackOrGroup[];
577
+ /** Vertical pixels reserved at the top of the group's extent for its
578
+ * label / chevron row, so the gutter can render a parent chevron
579
+ * above its children without overlapping the first child. The layout
580
+ * engine positions the first child (or summary when folded) at
581
+ * `yTop + headerHeight`. Default 0 — flush layout, matching the
582
+ * pre-nesting `interProTrack` behaviour where the group label
583
+ * shares the first sub-track's row. */
584
+ headerHeight?: number;
585
+ /** Optional one-row summary representation used when the group is folded.
586
+ * The viewer swaps `tracks` for `[summaryTrack]` while the group's id is
587
+ * in `collapsedGroupIds` and falls back to today's "remove rows" behaviour
588
+ * when omitted. Summary tracks follow the normal Track contract — they
589
+ * declare their own `coordSystem`, `heightPolicy`, `load`, and `render`,
590
+ * and live inside the figure SVG so exportSVG captures them. Convention
591
+ * is `heightPolicy: 'fixed'` with a small `px` (14–20 px) so folded
592
+ * groups land at a predictable height. */
593
+ summaryTrack?: Track;
594
+ }
595
+ export type TrackOrGroup = Track | TrackGroup;
596
+ export declare function isTrackGroup(item: TrackOrGroup): item is TrackGroup;
597
+ export interface DrawRectArgs {
598
+ x: number;
599
+ y: number;
600
+ width: number;
601
+ height: number;
602
+ rx?: number;
603
+ ry?: number;
604
+ fill?: string;
605
+ stroke?: string;
606
+ strokeWidth?: number;
607
+ vectorEffect?: string;
608
+ className?: string;
609
+ onClick?: () => void;
610
+ key?: string | number;
611
+ }
612
+ export interface DrawLineArgs {
613
+ x1: number;
614
+ y1: number;
615
+ x2: number;
616
+ y2: number;
617
+ stroke?: string;
618
+ strokeWidth?: number;
619
+ className?: string;
620
+ key?: string | number;
621
+ }
622
+ export interface DrawTextArgs {
623
+ x: number;
624
+ y: number;
625
+ text: string;
626
+ fontSize?: number;
627
+ fill?: string;
628
+ textAnchor?: 'start' | 'middle' | 'end';
629
+ dominantBaseline?: 'auto' | 'middle' | 'hanging' | 'central';
630
+ className?: string;
631
+ key?: string | number;
632
+ }
633
+ export interface DrawPathArgs {
634
+ d: string;
635
+ fill?: string;
636
+ stroke?: string;
637
+ strokeWidth?: number;
638
+ className?: string;
639
+ key?: string | number;
640
+ }
641
+ export interface DrawCircleArgs {
642
+ cx: number;
643
+ cy: number;
644
+ r: number;
645
+ fill?: string;
646
+ stroke?: string;
647
+ strokeWidth?: number;
648
+ className?: string;
649
+ key?: string | number;
650
+ }
651
+ export interface GroupArgs {
652
+ className?: string;
653
+ style?: Record<string, string | number>;
654
+ children: ReactNode;
655
+ key?: string | number;
656
+ }
657
+ export type PainterMode = 'screen' | 'export';
658
+ export interface Painter {
659
+ readonly mode: PainterMode;
660
+ placeInExonGroup(exonIdx: number, content: ReactNode): ReactNode;
661
+ placeInInterExon(exonIdxA: number, exonIdxB: number, content: ReactNode): ReactNode;
662
+ placeAbsolute(x: number, y: number, content: ReactNode): ReactNode;
663
+ drawRect(args: DrawRectArgs): ReactNode;
664
+ drawLine(args: DrawLineArgs): ReactNode;
665
+ drawText(args: DrawTextArgs): ReactNode;
666
+ drawPath(args: DrawPathArgs): ReactNode;
667
+ drawCircle(args: DrawCircleArgs): ReactNode;
668
+ group(args: GroupArgs): ReactNode;
669
+ color(varName: string, fallback?: string): string;
670
+ }
671
+ //# sourceMappingURL=types.d.ts.map