@weng-lab/genomebrowser 0.0.1 → 0.0.3

package/README.md

@@ -1,50 +1,125 @@
-# React + TypeScript + Vite
+# Genome Browser Component Library
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+## Installation
+`yarn add @weng-lab/genomebrowser`
 
-Currently, two official plugins are available:
+`npm install @weng-lab/genomebrowser`
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+## Usage
 
-## Expanding the ESLint configuration
+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.
 
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+### Walkthrough
+First, import the Genome Browser component:
+```tsx
+import { GenomeBrowser } from '@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,
+  zoomLevel: 148,
+  delta: 0,
+  tracks: []
+});
+```
+
+There are a few ways to add tracks to the browser.
+1. You can add a track by dispatching the `ADD_TRACK` action:
+```tsx
+import { BigWigTrackProps } from '@weng-lab/genomebrowser';
+const myBigWig: BigWigTrackProps = { ... }
+browserDispatch({ type: BrowserActionType.ADD_TRACK, track: myBigWig });
+```
+2. You can add a track by passing a track component as a child to the GenomeBrowser component:
+```tsx
+import { BigBedTrack } from '@weng-lab/genomebrowser';
+<GenomeBrowser browserState={browserState} browserDispatch={browserDispatch}>
+    <BigBedTrack ... />
+</GenomeBrowser>
+```
+3. You can also add a track by appending it to the 'tracks' array in the browser state:
+```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
+}
+```
 
-- Configure the top-level `parserOptions` property like this:
+## Full Example
 
-```js
-export default tseslint.config({
-  languageOptions: {
-    // other options...
-    parserOptions: {
-      project: ['./tsconfig.node.json', './tsconfig.app.json'],
-      tsconfigRootDir: import.meta.dirname,
-    },
-  },
-})
+```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"
+}
 ```
 
-- Replace `tseslint.configs.recommended` to `tseslint.configs.recommendedTypeChecked` or `tseslint.configs.strictTypeChecked`
-- Optionally add `...tseslint.configs.stylisticTypeChecked`
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and update the config:
-
-```js
-// eslint.config.js
-import react from 'eslint-plugin-react'
-
-export default tseslint.config({
-  // Set the react version
-  settings: { react: { version: '18.3' } },
-  plugins: {
-    // Add the react plugin
-    react,
-  },
-  rules: {
-    // other rules...
-    // Enable its recommended rules
-    ...react.configs.recommended.rules,
-    ...react.configs['jsx-runtime'].rules,
-  },
-})
+```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
+}
+
+function Main() {
+    const [browserState, browserDispatch] = useBrowserState(defaultState)
+
+    useEffect(() => {
+        // add a Transcript track to the state
+        browserDispatch({ type: BrowserActionType.ADD_TRACK, track: transcriptExample })
+    }, [])
+
+    return (
+        <GenomeBrowser browserState={browserState} browserDispatch={browserDispatch}>
+            <BigBedTrack {...bigBedExample} /> // add a BigBed track to the browser
+        </GenomeBrowser>
+    )
+}
 ```
+
+The browser will look something like this:
+![Browser Example](image.png)

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

@@ -0,0 +1,9 @@
+import { BrowserAction, BrowserState } from '../context/browserContext';
+import { default as React } from 'react';
+declare function GenomeBrowser({ children, browserState, browserDispatch, externalFetch }: {
+    children?: React.ReactNode;
+    browserState: BrowserState;
+    browserDispatch: React.Dispatch<BrowserAction>;
+    externalFetch?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export default GenomeBrowser;

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

@@ -0,0 +1,13 @@
+import { BrowserAction, BrowserState } from '../context/browserContext';
+export type TranscriptRequest = {
+    chromosome: string;
+    assembly: string;
+    start: number;
+    end: number;
+    version: number;
+};
+declare function GQLTracks({ browserState, browserDispatch }: {
+    browserState: BrowserState;
+    browserDispatch: React.Dispatch<BrowserAction>;
+}): null;
+export default GQLTracks;

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

@@ -0,0 +1,2 @@
+import { default as GenomeBrowser } from './browser';
+export { GenomeBrowser };

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

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+import { ToolTipData, ContextMenuData } from './types';
+import { DisplayMode } from '../tracks/types';
+export type MenuWrapperProps = {
+    onModeChange?: (id: string, displayMode: DisplayMode) => void;
+    children: React.ReactNode;
+};
+export type MenuState = {
+    tooltip: ToolTipData;
+    contextmenu: ContextMenuData;
+};
+/**
+ * Provides a genome browser container which wraps children in an SVG
+ * element and provides a mechanism for dragging to select regions.
+ */
+export default function MenuWrapper({ children, onModeChange }: MenuWrapperProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+import { Domain } from '../../utils/types';
+export type SelectRegionProps = {
+    domain: Domain;
+    width: number;
+    height: number;
+    dragRegionHeight: number;
+    leftMargin: number;
+    onSelectionEnd: (domain: Domain) => void;
+};
+declare const SelectRegion: React.FC<SelectRegionProps>;
+export default SelectRegion;

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

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+import { BrowserState } from '../context/browserContext';
+declare function Stacked({ children, browserState, rulerHeight }: {
+    children: React.ReactNode;
+    browserState: BrowserState;
+    rulerHeight: number;
+}): import("react/jsx-runtime").JSX.Element;
+export default Stacked;

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

@@ -0,0 +1,8 @@
+import { default as React, PropsWithChildren } from 'react';
+import { StackedTrackProps } from './types';
+/**
+ * Automatically stacks a number of child tracks on top of each other, updating y-coordinates
+ * appropriately as the tracks render themselves and update their heights.
+ */
+declare const StackedTracks: React.FC<PropsWithChildren<StackedTrackProps>>;
+export default StackedTracks;

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

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

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

@@ -0,0 +1,55 @@
+import { Domain } from '../../utils/types';
+export type GenomeBrowserDomainChangedAction = {
+    type: "domainChanged";
+    newDomain: Domain;
+};
+export type GenomeBrowserHeightChangedAction = {
+    type: "heightChanged";
+    newHeight: number;
+};
+export type GenomeBrowserTooltipChangedAction = {
+    type: "tooltipChanged";
+    tooltip: ToolTipData;
+};
+export type GenomeBrowserContextMenuChangedAction = {
+    type: "contextMenuChanged";
+    contextmenu: ContextMenuData;
+};
+export type ToolTipData = {
+    show: boolean;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    content?: React.ReactElement;
+};
+export type ContextMenuData = {
+    show: boolean;
+    x: number;
+    y: number;
+    id: string;
+    displayMode?: string;
+    displayModeOptions?: string[];
+    downloadSVG?: () => void;
+};
+export type GenomeBrowserAction = GenomeBrowserDomainChangedAction | GenomeBrowserHeightChangedAction | GenomeBrowserTooltipChangedAction | GenomeBrowserContextMenuChangedAction;
+export type StackedTrackProps = {
+    id: string;
+    transform?: string;
+    height?: number;
+    onHeightChanged?: (height: number) => void;
+    svgRef?: React.RefObject<SVGSVGElement>;
+};
+export type StackedTrackState = {
+    heights: number[];
+};
+export type StackedTrackChildHeightChangedAction = {
+    type: "childHeightChanged";
+    index: number;
+    height: number;
+};
+export type StackedTrackChildrenAddedAction = {
+    type: "childrenAdded";
+    heights: number[];
+};
+export type StackedTrackAction = StackedTrackChildHeightChangedAction | StackedTrackChildrenAddedAction;

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

@@ -0,0 +1 @@
+export declare const useEvent: (event: any, handler: (e: KeyboardEvent) => void, passive?: boolean) => void;

package/dist/components/clipPath/clipPath.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+export type ClipPathProps = {
+    height: number;
+    width: number;
+    id: string;
+};
+/**
+ * Creates an SVG clipPath element with a unique ID.
+ * @param width the width of the element relative to the SVG.
+ * @param height the height of the element relative to the SVG.
+ * @param id the unqiue ID of the element, used to refer to it in properties of clipped elements.
+ */
+declare const ClipPath: React.FC<ClipPathProps>;
+export default ClipPath;

package/dist/components/context/browserContext.d.ts

@@ -0,0 +1,113 @@
+import { Domain, YRange } from '../../utils/types';
+import { TrackProps } from '../tracks/types';
+import { TranscriptOptions } from '../tracks/transcripts/transcript';
+import { BigWigOptions } from '../tracks/bigwig/bigwig';
+import { BigBedOptions } from '../tracks/bigbed/bigbed';
+export declare const BrowserStateContext: import('react').Context<BrowserState>;
+export declare const BrowserDispatchContext: import('react').Context<import('react').Dispatch<BrowserAction>>;
+export type BrowserState = {
+    domain: Domain;
+    preRenderedWidth: number;
+    width: number;
+    zoomLevel: number;
+    delta: number;
+    tracks: TrackProps[];
+};
+export declare enum BrowserActionType {
+    SET_DOMAIN = "setDomain",
+    SHIFT_DOMAIN = "shiftDomain",
+    ADD_TRACK = "addTrack",
+    UPDATE_TRACK = "updateTrack",
+    SET_TRACK_HEIGHT = "setTrackHeight",
+    SET_TRACK_DATA = "setTrackData",
+    SET_LOADING = "setLoading",
+    SWAP_TRACKS = "swapTracks",
+    RELOAD_TRACKS = "reloadTracks",
+    SHIFT_TRACK = "shiftTrack",
+    REMOVE_TRANSLATION = "removeTranslation",
+    INSERT_TRACK = "insertTrack",
+    DELETE_TRACK = "deleteTrack",
+    TRANSLATE_TRACK = "translateTrack",
+    SET_RANGE = "setRange",
+    UPDATE_PROPS = "updateProps",
+    BRING_TO_TOP = "bringToTop",
+    SET_DELTA = "setDelta"
+}
+export type BrowserAction = SetDomain | AddTrack | UpdateTrack | SetTrackHeight | SetTrackData | SwapTracks | ShiftDomain | SetLoading | ShiftTrack | RemoveTranslation | InsertTrack | DeleteTrack | TranslateTrack | SetRange | UpdateProps | BringToTop | SetDelta;
+export type SetDelta = {
+    type: BrowserActionType.SET_DELTA;
+    delta: number;
+};
+export type SetDomain = {
+    type: BrowserActionType.SET_DOMAIN;
+    domain: Domain;
+};
+export type AddTrack = {
+    type: BrowserActionType.ADD_TRACK;
+    track: TrackProps;
+};
+export type UpdateTrack = {
+    type: BrowserActionType.UPDATE_TRACK;
+    id: string;
+    track: Partial<TrackProps>;
+};
+export type SetTrackHeight = {
+    type: BrowserActionType.SET_TRACK_HEIGHT;
+    id: string;
+    height: number;
+};
+export type SetTrackData = {
+    type: BrowserActionType.SET_TRACK_DATA;
+    id: string;
+    data: any;
+};
+export type SwapTracks = {
+    type: BrowserActionType.SWAP_TRACKS;
+    id1: string;
+    id2: string;
+};
+export type ShiftDomain = {
+    type: BrowserActionType.SHIFT_DOMAIN;
+    delta: number;
+};
+export type SetLoading = {
+    type: BrowserActionType.SET_LOADING;
+};
+export type ShiftTrack = {
+    type: BrowserActionType.SHIFT_TRACK;
+    id1: string;
+    id2: string;
+};
+export type RemoveTranslation = {
+    type: BrowserActionType.REMOVE_TRANSLATION;
+    id: string;
+};
+export type InsertTrack = {
+    type: BrowserActionType.INSERT_TRACK;
+    index: number;
+    track: TrackProps;
+};
+export type DeleteTrack = {
+    type: BrowserActionType.DELETE_TRACK;
+    id: string;
+};
+export type TranslateTrack = {
+    type: BrowserActionType.TRANSLATE_TRACK;
+    id: string;
+    dist: number;
+};
+export type SetRange = {
+    type: BrowserActionType.SET_RANGE;
+    id: string;
+    range: YRange;
+};
+export type UpdateProps = {
+    type: BrowserActionType.UPDATE_PROPS;
+    id: string;
+    props: TranscriptOptions | BigWigOptions | BigBedOptions;
+};
+export type BringToTop = {
+    type: BrowserActionType.BRING_TO_TOP;
+    id: string;
+};
+export declare function BrowserReducer(state: BrowserState, action: BrowserAction): BrowserState;

package/dist/components/context/domainContext.d.ts

@@ -0,0 +1,9 @@
+import { Domain } from '../../utils/types';
+type stateContext<T> = [
+    T,
+    React.Dispatch<React.SetStateAction<T>>
+];
+export declare const DomainContext: import('react').Context<Domain>;
+export declare const DomainDispatchContext: import('react').Context<any>;
+export declare const DeltaContext: import('react').Context<stateContext<number>>;
+export {};

package/dist/components/context/providers.d.ts

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+import { BrowserState, BrowserAction } from './browserContext';
+import { TrackModalInfo } from '../../hooks/useModal';
+export declare const ModalContext: import('react').Context<{
+    openModal: TrackModalInfo | null;
+    showModal: (trackId: string, mouseX: number, mouseY: number) => void;
+    closeModal: () => void;
+}>;
+interface ContextObjects {
+    children: ReactNode;
+    browserState: BrowserState;
+    browserDispatch: React.Dispatch<BrowserAction>;
+    deltaContext: [number, React.Dispatch<React.SetStateAction<number>>];
+    modalState: {
+        openModal: TrackModalInfo | null;
+        showModal: (trackId: string, mouseX: number, mouseY: number) => void;
+        closeModal: () => void;
+    };
+}
+export default function ContextProvider({ children, browserState, browserDispatch, modalState, deltaContext }: ContextObjects): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/controls/custombigwig.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { CustomBigWigProps } from './types';
+declare const CustomBigWig: React.FC<CustomBigWigProps>;
+export default CustomBigWig;

package/dist/components/controls/index.d.ts

@@ -0,0 +1,6 @@
+import { default as ShiftButton } from './shiftbutton';
+import { default as ZoomButton } from './zoombutton';
+import { default as InputRegion } from './inputregion';
+import { default as UCSCControls } from './ucsc';
+import { default as CustomBigWig } from './custombigwig';
+export { ShiftButton, ZoomButton, InputRegion, CustomBigWig, UCSCControls };

package/dist/components/controls/inputregion.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { InputRegionProps } from './types';
+declare const InputRegion: React.FC<InputRegionProps>;
+export default InputRegion;

package/dist/components/controls/shiftbutton.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { ShiftButtonProps } from './types';
+declare const ShiftButton: React.FC<ShiftButtonProps>;
+export default ShiftButton;

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

@@ -0,0 +1,33 @@
+import { Domain } from '../../utils/types';
+export type CustomBigWigProps = {
+    text: string;
+    onSubmit: (value: CustomBigWig) => void;
+};
+export type CustomBigWig = {
+    url: string;
+    title: string;
+};
+export type InputRegionProps = {
+    text?: string;
+    domain: Domain;
+    chromosome?: string;
+    size: number;
+    onSubmit: (domain: Domain) => void;
+};
+export type ShiftButtonProps = {
+    text: string;
+    shift: number;
+    domain: Domain;
+    onClick: (domain: Domain) => void;
+};
+export type ZoomButtonProps = {
+    text: string;
+    factor: number;
+    domain: Domain;
+    onClick: (domain: Domain) => void;
+};
+export type UCSCControlProps = {
+    domain: Domain;
+    onDomainChanged: (domain: Domain) => void;
+    withInput: boolean;
+};

package/dist/components/controls/ucsc.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { UCSCControlProps } from './types';
+declare const UCSCControls: React.FC<UCSCControlProps>;
+export default UCSCControls;

package/dist/components/controls/zoombutton.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { ZoomButtonProps } from './types';
+declare const ZoomButton: React.FC<ZoomButtonProps>;
+export default ZoomButton;

package/dist/components/cytobands/centromere.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { CentromereProps } from './types';
+declare const Centromere: React.FC<CentromereProps>;
+export default Centromere;

package/dist/components/cytobands/cytoband.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { CytobandProps } from './types';
+declare const Cytoband: React.FC<CytobandProps>;
+export default Cytoband;

package/dist/components/cytobands/cytobands.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { CytobandsProps } from './types';
+declare const Cytobands: React.FC<CytobandsProps>;
+export default Cytobands;

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

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { CytobandHighlightProps } from './types';
+declare const CytobandHighlight: React.FC<CytobandHighlightProps>;
+export default CytobandHighlight;

package/dist/components/cytobands/index.d.ts

@@ -0,0 +1,3 @@
+import { default as Cytobands } from './cytobands';
+export { type CytobandsProps, type Cytoband, type CytobandColors } from './types';
+export { Cytobands };

package/dist/components/cytobands/shorthighlight.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { ShortHighlightProps } from './types';
+declare const ShortHighlight: React.FC<ShortHighlightProps>;
+export default ShortHighlight;

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

@@ -0,0 +1,61 @@
+import { default as React } from 'react';
+import { Domain } from '../../utils/types';
+export type Highlight = {
+    color: string;
+    start: number;
+    end: number;
+};
+export type ShortHighlightProps = {
+    highlight: Highlight;
+    x: (value: number) => number;
+    height: number;
+};
+export type Cytoband = {
+    stain: string;
+    coordinates: Domain;
+};
+export type CytobandColors = {
+    default: string;
+    centromere: string;
+    stalk: string;
+};
+export type CytobandsProps = {
+    data: Cytoband[];
+    width: number;
+    height: number;
+    id: string;
+    colors?: CytobandColors;
+    transform?: string;
+    highlight?: Highlight;
+    highlights?: Highlight[];
+    onHighlightMouseOver?: (highlight: Highlight, x: number, i: number) => void;
+    onHighlightMouseOut?: () => void;
+    onHighlightClick?: (highlight: Highlight, x: number, i: number) => void;
+    domain: Domain;
+    children?: React.ReactNode;
+    opacity?: number;
+};
+export type CytobandProps = {
+    colors: CytobandColors;
+    width: number;
+    height: number;
+    type: string;
+    x: number;
+    opacity?: number;
+};
+export type CentromereProps = {
+    color: string;
+    width: number;
+    height: number;
+    x: number;
+    opening: boolean;
+};
+export type CytobandHighlightProps = {
+    x: (value: number) => number;
+    height: number;
+    width: number;
+    highlight: Highlight;
+    onMouseOver?: () => void;
+    onMouseOut?: () => void;
+    onClick?: () => void;
+};

package/dist/components/icons/error.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { ErrorIconProps } from './types';
+/**
+ * An error icon, consisting of a red exclamation point inside a triangle.
+ * @param width the width of the icon relative to the containing SVG.
+ * @param height the height of the icon relative to the containing SVG.
+ */
+declare const ErrorIcon: React.FC<ErrorIconProps>;
+export default ErrorIcon;

package/dist/components/icons/index.d.ts

@@ -0,0 +1,3 @@
+import { default as LoadingSpinner } from './spinner';
+import { default as ErrorIcon } from './error';
+export { LoadingSpinner, ErrorIcon };