@weng-lab/genomebrowser 0.0.24 → 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Weng Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,124 +1,211 @@
-# Genome Browser Component Library
+# Genome Browser
 
-## Installation
-`yarn add @weng-lab/genomebrowser`
+A powerful, interactive React-based genome browser for visualizing genomic data. Built with TypeScript, Vite, and modern web technologies.
 
-`npm install @weng-lab/genomebrowser`
+## Features
 
-## Usage
+- 🧬 **Multiple Track Types**: BigWig, BigBed, BulkBed, Transcript, Motif, and Importance tracks
+- 🎛️ **Interactive Controls**: Smooth pan and zoom with crisp SVG graphics, drag-and-drop track reordering
+- 🔧 **Customizable**: Configurable colors, heights, display modes, and styling
+- 📊 **Efficient Data Loading**: GraphQL-based API with intelligent batching
+- 🖱️ **Rich Interactions**: Click and hover on genomic features with tooltips and real-time updates
+- 📱 **Responsive**: Works across different screen sizes with consistently sharp graphics
+- ⚡ **Performance**: Optimized rendering with React and Zustand state management
+- 🎨 **SVG-Based**: Uses Scalable Vector Graphics (SVG) for crisp, resolution-independent rendering that scales beautifully
+- 🔍 **Publication Ready**: Export high-quality SVG images suitable for papers and presentations
 
-The library revolves around creating tracks and adding them to the browser. To do this, first you import the Genome Browser component, creating the browser state and dispatch function, and adding your tracks to the state. Then you pass the state and dispatch function to the GenomeBrowser component as props.
+## Installation
 
-### Walkthrough
-First, import the Genome Browser component:
-```tsx
-import { GenomeBrowser } from '@weng-lab/genomebrowser';
+```bash
+npm install @weng-lab/genomebrowser
 ```
-Then you create the browser state and dispatch function with the `useBrowserState` hook:
 
-```tsx
-import { useBrowserState } from '@weng-lab/genomebrowser';
-const [browserState, browserDispatch] = useBrowserState({
-  domain: { chromosome: "chr11", start: 5220000, end: 5420000 },
-  preRenderedWidth: 1350,
-  width: 1500,
-  tracks: [],
-  highlights: []
-});
+```bash
+yarn add @weng-lab/genomebrowser
+```
+
+```bash
+pnpm add @weng-lab/genomebrowser
 ```
 
-There are a few ways to add tracks to the browser.
-1. You can add a track by dispatching the `ADD_TRACK` action:
+## Quick Start
+
 ```tsx
-import { BigWigTrackProps } from '@weng-lab/genomebrowser';
-const myBigWig: BigWigTrackProps = { ... }
-browserDispatch({ type: BrowserActionType.ADD_TRACK, track: myBigWig });
+import React from "react";
+import { Browser, Track, InitialBrowserState, createBrowserStore, createTrackStore, BrowserStoreInstance } from "@weng-lab/genomebrowser";
+
+function GenomeBrowserExample() {
+  // Define your tracks
+  const initialTracks: Track[] = [...];
+
+  // Configure initial browser state
+  const initialState: InitialBrowserState = {
+    domain: {
+      chromosome: "chr12",
+      start: 53360037,
+      end: 53400206,
+    },
+    marginWidth: 150,
+    trackWidth: 1350,
+    multiplier: 3, // a multiplier to fetch more data for smooth panning
+  };
+
+  // Create stores to hold browser data
+  const browserStore = createBrowserStore(initialState)
+  const trackStore = createTrackStore(initialTracks)
+
+  return (
+    <div style={{ width: "90%", margin: "0 auto" }}>
+      <h1>My Genome Browser</h1>
+      <DomainDisplay browserStore={browserStore} />
+      <Browser browserStore={browserStore} trackStore={trackStore} />
+    </div>
+  );
+}
+
+// Use the stores to access information
+function DomainDisplay({browserStore} : {browserStore: BrowserStoreInstance}) {
+  // Zustand-like selectors for getting fields and functions
+  const domain = browserStore((state) => state.domain)
+  return (
+    <h1>{domain.chromosome}:{domain.start}-{domain.end}</h1>
+  )
+}
+
 ```
-2. You can add a track by passing a track component as a child to the GenomeBrowser component:
+
+## Browser Configuration
+
+### State Example
+
 ```tsx
-import { BigBedTrack } from '@weng-lab/genomebrowser';
-<GenomeBrowser browserState={browserState} browserDispatch={browserDispatch}>
-    <BigBedTrack ... />
-</GenomeBrowser>
+const initialState: InitialBrowserState = {
+  domain: {
+    chromosome: "chr1",
+    start: 1000000,
+    end: 2000000,
+  },
+  marginWidth: 150, // Width of the track margins
+  trackWidth: 1350, // Width of the viewable track area
+  multiplier: 3, // Data fetching multiplier for smooth panning
+  highlights: [
+    // Optional: initial highlights
+    {
+      id: "highlight1",
+      color: "#ffaabb",
+      domain: { chromosome: "chr1", start: 1500000, end: 1600000 },
+    },
+  ],
+};
 ```
-3. You can also add a track by appending it to the 'tracks' array in the browser state:
+
+## Track Examples
+
+### BigWig Tracks
+
+Display continuous signal data (e.g., ChIP-seq, RNA-seq signals).
+
 ```tsx
-import { BigWigTrackProps, BrowserState } from '@weng-lab/genomebrowser';
-const myBigWig: BigWigTrackProps = { ... }
-const myState: BrowserState = {
-    domain: { chromosome: "chr11", start: 5220000, end: 5420000 },
-    ... // initialize the rest of the state
-    tracks: [myBigWig] // add the track to the state
+{
+  id: "signal",
+  title: "Signal Data",
+  trackType: TrackType.BigWig,
+  displayMode: DisplayMode.Full, // Multiple display modes supported
+  height: 100,
+  color: "#3498db",
+  url: "https://example.com/signal.bw",
 }
 ```
 
-## Full Example
+### BigBed Tracks
+
+Display discrete genomic regions (e.g., peaks, annotations).
 
 ```tsx
-// in trackExamples.ts
-export const bigWigExample: BigWigTrackProps = {
-    ...DefaultBigWig,
-    id: "1",
-    title: "bigwig",
-    height: 100,
-    url: "https://downloads.wenglab.org/DNAse_All_ENCODE_MAR20_2024_merged.bw",
-    color: "blue"
-}
-export const bigBedExample: BigBedTrackProps = {
-    ...DefaultBigBed,
-    id: "2",
-    title: "bigbed",
-    height: 75,
-    rowHeight: 12,
-    color: "red",
-    url: "https://downloads.wenglab.org/GRCh38-cCREs.DCC.bigBed"
-}
-export const transcriptExample: TranscriptTrackProps = {
-    ...DefaultTranscript,
-    id: "3",
-    title: "transcript",
-    rowHeight: 12,
-    assembly: "GRCh38",
-    queryType: "gene",
-    version: TranscriptHumanVersion.V47,
-    height: 100,
-    color: "green"
+{
+  id: "peaks",
+  title: "Peak Calls",
+  trackType: TrackType.BigBed,
+  displayMode: DisplayMode.Dense,
+  height: 20,
+  color: "#e74c3c",
+  url: "https://example.com/peaks.bigBed",
+  onClick: (rect) => console.log("Clicked:", rect), // Mouse interactivitiy
+  onHover: (rect) => console.log("Hovered:", rect),
+  tooltip: (rect) => <text>{rect.name}</text>, // Custom svg tooltips
 }
 ```
 
+### BulkBed Tracks
+
+Display multiple BigBed datasets in a single track.
+
 ```tsx
-// in main.tsx
-import { useEffect } from 'react'
-import {
-    GenomeBrowser, BrowserState, BrowserActionType, useBrowserState,
-    BigBedTrack
-} from '../lib'
-import { bigWigExample, bigBedExample, transcriptExample } from './trackExamples'
-
-const defaultState: BrowserState = {
-    domain: { chromosome: "chr11", start: 5220000, end: 5420000 },
-    preRenderedWidth: 1350,
-    width: 1500,
-    zoomLevel: 148,
-    delta: 0,
-    tracks: [bigWigExample] // adds a BigWig track to the state
+{
+  id: "bulk-data",
+  title: "Multiple Datasets",
+  trackType: TrackType.BulkBed,
+  displayMode: DisplayMode.Full,
+  height: 40,
+  gap: 2, // Gap between datasets
+  color: "#9b59b6",
+  datasets: [
+    { name: "Dataset 1", url: "https://example.com/data1.bigBed" },
+    { name: "Dataset 2", url: "https://example.com/data2.bigBed" },
+  ],
 }
+```
 
-function Main() {
-    const [browserState, browserDispatch] = useBrowserState(defaultState)
+### Transcript Tracks
 
-    useEffect(() => {
-        // add a Transcript track to the state
-        browserDispatch({ type: BrowserActionType.ADD_TRACK, track: transcriptExample })
-    }, [])
+Display gene annotations and transcripts.
 
-    return (
-        <GenomeBrowser browserState={browserState} browserDispatch={browserDispatch}>
-            <BigBedTrack {...bigBedExample} /> // add a BigBed track to the browser
-        </GenomeBrowser>
-    )
+```tsx
+{
+  id: "genes",
+  title: "Gene Annotations",
+  trackType: TrackType.Transcript,
+  displayMode: DisplayMode.Squish,
+  height: 50,
+  color: "#2ecc71",
+  assembly: "GRCh38", // "mm10" also supported
+  version: 47, // GENCODE version
 }
 ```
 
-The browser will look something like this:
-![Browser Example](https://github.com/weng-lab/genomebrowser-components/blob/master/image.png)
+Explore our comprehensive [Storybook]() documentation for detailed information about additional track types and their configuration options.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Run Storybook for component development
+npm run storybook
+
+# Build for production
+npm run build
+
+# Run linting
+npm run lint
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Support
+
+For questions and support, please open an issue on GitHub.

package/dist/api/DataFetcher.d.ts

@@ -0,0 +1,2 @@
+declare function DataFetcher(): null;
+export default DataFetcher;

package/dist/api/apiTypes.d.ts

@@ -0,0 +1,61 @@
+/**
+ * All request and response types for the genome browser API
+ */
+export interface BigRequest {
+    url: string;
+    chr1: string;
+    start: number;
+    end: number;
+}
+export interface BigResponse {
+    bigRequests: {
+        data: any;
+    }[];
+}
+export interface TranscriptRequest {
+    chromosome: string;
+    assembly: string;
+    start: number;
+    end: number;
+    version: number;
+}
+export interface TranscriptResponse {
+    gene: any;
+}
+export interface MotifRequest {
+    consensus_regex: string;
+    peaks_accession: string;
+    range: {
+        chromosome: string;
+        start: number;
+        end: number;
+    };
+    assembly: string;
+    prange: {
+        chrom: string;
+        chrom_start: number;
+        chrom_end: number;
+    };
+}
+export interface MotifResponse {
+    meme_occurrences: any[];
+    peaks: {
+        peaks: any[];
+    };
+}
+export interface LDRequest {
+    assembly: string;
+    coordinates: {
+        chromosome: string;
+        start: number;
+        end: number;
+    };
+}
+export interface LDResponse {
+    snpQuery: any[];
+}
+export interface MotifRect {
+    start: number;
+    end: number;
+    pwm?: number[][];
+}

package/dist/{components/tracks/ld → api}/queries.d.ts

@@ -1,3 +1,7 @@
-import { Population } from './types';
+/**
+ * All GraphQL queries for the genome browser
+ */
+export declare const BIGDATA_QUERY: import('graphql').DocumentNode;
+export declare const TRANSCRIPT_GENES_QUERY: import('graphql').DocumentNode;
+export declare const MOTIF_QUERY: import('graphql').DocumentNode;
 export declare const VARIANT_QUERY = "\n  query SNP($assembly: String!, $coordinates: [GenomicRangeInput]) {\n    snpQuery(assembly: $assembly, coordinates: $coordinates, common: true) {\n      id\n      coordinates {\n        chromosome\n        start\n        end\n      }\n    }\n  }\n";
-export declare const LD_QUERY: (populations: Population[]) => string;

package/dist/api/queryExecutor.d.ts

@@ -0,0 +1,14 @@
+import { AllRequests } from './requestBuilder';
+import { LazyQueryExecFunction, OperationVariables } from '@apollo/client';
+export interface QueryExecutors {
+    fetchBigData: LazyQueryExecFunction<unknown, OperationVariables>;
+    fetchGene: LazyQueryExecFunction<unknown, OperationVariables>;
+    fetchMotif: LazyQueryExecFunction<unknown, OperationVariables>;
+    fetchImportance: LazyQueryExecFunction<unknown, OperationVariables>;
+    fetchBulkBed: LazyQueryExecFunction<unknown, OperationVariables>;
+    fetchSnps: LazyQueryExecFunction<unknown, OperationVariables>;
+}
+/**
+ * Execute all queries concurrently based on built requests
+ */
+export declare function executeAllQueries(requests: AllRequests, executors: QueryExecutors): Promise<void>;

package/dist/api/requestBuilder.d.ts

@@ -0,0 +1,40 @@
+import { Domain } from '../utils/types';
+import { Track } from '../store/trackStore';
+import { BigRequest, TranscriptRequest, MotifRequest, LDRequest } from './apiTypes';
+export interface AllRequests {
+    bigRequests: BigRequest[];
+    transcriptRequest?: TranscriptRequest;
+    motifRequest?: MotifRequest;
+    importanceRequests: BigRequest[];
+    bulkBedRequests: BigRequest[];
+    ldRequest?: LDRequest;
+}
+/**
+ * Build BigWig/BigBed requests for given tracks
+ */
+export declare function buildBigRequests(tracks: Track[], domain: Domain): BigRequest[];
+/**
+ * Build BulkBed requests for given tracks
+ */
+export declare function buildBulkBedRequests(tracks: Track[], domain: Domain): BigRequest[];
+/**
+ * Build transcript request for given tracks (first transcript track found)
+ */
+export declare function buildTranscriptRequest(tracks: Track[], domain: Domain): TranscriptRequest | undefined;
+/**
+ * Build motif request for given tracks (first motif track found)
+ */
+export declare function buildMotifRequest(tracks: Track[], domain: Domain): MotifRequest | undefined;
+/**
+ * Build importance requests for given tracks (first importance track found)
+ * Use currentDomain to get only the viewable region (avoids large requests)
+ */
+export declare function buildImportanceRequests(tracks: Track[], currentDomain: Domain): BigRequest[];
+/**
+ * Build LD request for given tracks (first LD track found)
+ */
+export declare function buildLDRequest(tracks: Track[], domain: Domain): LDRequest | undefined;
+/**
+ * Build all requests for all track types in one coordinated call
+ */
+export declare function buildAllRequests(tracks: Track[], expandedDomain: Domain, currentDomain: Domain): AllRequests;

package/dist/api/resultsProcessor.d.ts

@@ -0,0 +1,26 @@
+import { ApolloError } from '@apollo/client';
+import { Track } from '../store/trackStore';
+import { BigResponse, TranscriptResponse, MotifResponse, LDResponse } from './apiTypes';
+export interface QueryResults {
+    bigData?: BigResponse;
+    geneData?: TranscriptResponse;
+    motifData?: MotifResponse;
+    importanceData?: BigResponse;
+    bulkBedData?: BigResponse;
+    snpData?: LDResponse;
+    bigError?: ApolloError;
+    geneError?: ApolloError;
+    motifError?: ApolloError;
+    importanceError?: ApolloError;
+    bulkBedError?: ApolloError;
+    snpError?: ApolloError;
+}
+export interface ProcessedResult {
+    trackId: string;
+    data: unknown;
+    error?: ApolloError;
+}
+/**
+ * Process all query results and return organized data for each track
+ */
+export declare function processAllResults(tracks: Track[], results: QueryResults): ProcessedResult[];

package/dist/components/browser/browser.d.ts

@@ -1,9 +1,8 @@
-import { BrowserAction, BrowserState } from '../context/browserContext';
-import { default as React } from 'react';
-declare function GenomeBrowser({ children, width, browserState, browserDispatch }: {
-    children?: React.ReactNode;
-    width: number | string;
-    browserState: BrowserState;
-    browserDispatch: React.Dispatch<BrowserAction>;
-}): import("react/jsx-runtime").JSX.Element;
-export default GenomeBrowser;
+import { BrowserStoreInstance } from '../../store/browserStore';
+import { TrackStoreInstance } from '../../store/trackStore';
+interface BrowserProps {
+    browserStore: BrowserStoreInstance;
+    trackStore: TrackStoreInstance;
+}
+export default function Browser({ browserStore, trackStore }: BrowserProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/browser/svgWrapper.d.ts

@@ -1,9 +1,3 @@
-interface SvgWrapperProps {
-    width: number | string;
-    innerWidth: number;
-    height: number;
-    svgRef?: React.RefObject<SVGSVGElement>;
+export default function SvgWrapper({ children }: {
     children: React.ReactNode;
-}
-export default function SvgWrapper({ width, innerWidth, height, svgRef, children }: SvgWrapperProps): import("react/jsx-runtime").JSX.Element;
-export {};
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/contextMenu/contextMenu.d.ts

@@ -0,0 +1 @@
+export default function ContextMenu(): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/highlight/highlights.d.ts

@@ -0,0 +1 @@
+export default function Highlights(): import("react/jsx-runtime").JSX.Element;

package/dist/components/highlight/types.d.ts

@@ -0,0 +1,9 @@
+export interface Highlight {
+    id: string;
+    domain: {
+        chromosome?: string;
+        start: number;
+        end: number;
+    };
+    color: string;
+}

package/dist/components/modal/bigWig/range.d.ts

@@ -0,0 +1,6 @@
+import { YRange } from '../../tracks/bigwig/types';
+export default function Range({ id, defaultRange, customRange, }: {
+    id: string;
+    defaultRange: YRange | undefined;
+    customRange: YRange | undefined;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/modal/bulkbed/datasetList.d.ts

@@ -0,0 +1,4 @@
+import { BulkBedDataset } from '../../tracks/bulkbed/types';
+export default function DatasetList({ datasets }: {
+    datasets: BulkBedDataset[];
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/modal/bulkbed/gap.d.ts

@@ -0,0 +1,4 @@
+export default function Gap({ id, defaultGap }: {
+    id: string;
+    defaultGap: number;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/modal/modal.d.ts

@@ -1,2 +1,4 @@
-export default function TrackModal(): import('react').ReactPortal | null;
+export default function Modal(): import("react/jsx-runtime").JSX.Element | null;
 export declare function getTextColor(backgroundColor: string): string;
+export declare function shadeColor(color: string, percent: number): string;
+export declare const isDark: (color: string) => boolean;

package/dist/components/modal/{forms/universalForm.d.ts → shared/base.d.ts}

@@ -1,4 +1,4 @@
-import { TrackProps } from '../../tracks/types';
+import { Track } from '../../../store/trackStore';
 export default function UniversalForm({ track }: {
-    track: TrackProps;
+    track: Track;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/components/modal/shared/display.d.ts

@@ -0,0 +1,5 @@
+import { TrackType } from '../../tracks/types';
+export default function Display({ id, trackType }: {
+    id: string;
+    trackType: TrackType;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/modal/shared/download.d.ts

@@ -0,0 +1,15 @@
+import { Track } from '../../../store/trackStore';
+export declare const downloadButtonStyle: {
+    cursor: string;
+    outline: number;
+    color: string;
+    borderColor: string;
+    border: string;
+    borderRadius: string;
+    display: string;
+    textAlign: "center";
+    padding: string;
+};
+export declare function DownloadForm({ track }: {
+    track: Track;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/modal/{forms → shared}/form.d.ts

@@ -1,3 +1,4 @@
-export default function Form({ children }: {
+export default function Form({ title, children }: {
+    title: string;
     children: React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/components/modal/shared/height.d.ts

@@ -0,0 +1,4 @@
+export default function Height({ id, defaultHeight }: {
+    id: string;
+    defaultHeight: number;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/modal/shared/value.d.ts

@@ -0,0 +1,5 @@
+export default function Value({ defaultValue, validate, callback, }: {
+    defaultValue: number;
+    validate: (value: string) => string | undefined;
+    callback: (value: string) => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/modal/transcript/geneName.d.ts

@@ -0,0 +1,4 @@
+export default function GeneName({ id, name }: {
+    id: string;
+    name: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/modal/transcript/version.d.ts

@@ -0,0 +1,13 @@
+import { TranscriptConfig } from '../../tracks/transcript/types';
+export declare enum TranscriptHumanVersion {
+    V29 = 29,
+    V40 = 40,
+    V47 = 47
+}
+export declare enum TranscriptMouseVersion {
+    V21 = 21,
+    V25 = 25
+}
+export default function TranscriptForm({ track }: {
+    track: TranscriptConfig;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/tooltip/defaultTooltip.d.ts

@@ -0,0 +1,3 @@
+export default function DefaultTooltip({ value }: {
+    value: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/tooltip/tooltip.d.ts

@@ -1,4 +1 @@
-import { default as React, PropsWithChildren } from 'react';
-import { TooltipProps } from './types';
-declare const Tooltip: React.FC<PropsWithChildren<TooltipProps>>;
-export default Tooltip;
+export default function Tooltip(): import("react/jsx-runtime").JSX.Element | null;