@weng-lab/genomebrowser-ui 0.1.11 → 0.2.0-beta.0

package/src/TrackSelect/Folders/biosamples/shared/treeBuilder.ts

@@ -0,0 +1,227 @@
+import { TreeViewBaseItem } from "@mui/x-tree-view";
+import { ExtendedTreeItemProps } from "../../../types";
+import { BiosampleRowInfo } from "./types";
+import { assayTypes, ontologyTypes, formatAssayType } from "./constants";
+
+/** Format an ID like "h3k27ac-ENCFF922YMQ" or "folder::h3k27ac-ENCFF922YMQ" to "H3K27ac - ENCFF922YMQ" */
+function formatIdLabel(id: string): string {
+  // Remove folder prefix if present (e.g., "FolderName::h3k27ac-ENCFF922YMQ" -> "h3k27ac-ENCFF922YMQ")
+  const rawId = id.includes("::") ? id.split("::").pop()! : id;
+
+  const hyphenIndex = rawId.indexOf("-");
+  if (hyphenIndex === -1) return rawId;
+
+  const assayPart = rawId.substring(0, hyphenIndex);
+  const accessionPart = rawId.substring(hyphenIndex + 1);
+
+  return `${formatAssayType(assayPart)} - ${accessionPart}`;
+}
+
+/**
+ * Creates the root node for the tree view
+ */
+function createRootNode(
+  label: string,
+  folderId: string,
+): TreeViewBaseItem<ExtendedTreeItemProps> {
+  return {
+    id: `${folderId}::root`,
+    label,
+    icon: "folder",
+    children: [],
+    allExpAccessions: [],
+  };
+}
+
+/**
+ * Builds tree in the sorted by assay view
+ * Hierarchy: Assay -> Ontology -> DisplayName -> Experiment
+ *
+ * @param selectedIds - list of selected row IDs
+ * @param rowById - Mapping between an id and its BiosampleRowInfo object
+ * @param rootLabel - Label for the root node
+ * @param folderId - Folder ID to prefix tree item IDs with
+ * @returns tree items for the RichTreeView
+ */
+export function buildSortedAssayTreeView(
+  selectedIds: string[],
+  rowById: Map<string, BiosampleRowInfo>,
+  rootLabel: string = "Biosamples",
+  folderId: string = "",
+): TreeViewBaseItem<ExtendedTreeItemProps>[] {
+  const root = createRootNode(rootLabel, folderId);
+  const assayMap = new Map<string, TreeViewBaseItem<ExtendedTreeItemProps>>();
+  const ontologyMap = new Map<
+    string,
+    TreeViewBaseItem<ExtendedTreeItemProps>
+  >();
+  const displayNameMap = new Map<
+    string,
+    TreeViewBaseItem<ExtendedTreeItemProps>
+  >();
+
+  const selectedRows = selectedIds.reduce<BiosampleRowInfo[]>((acc, id) => {
+    const row = rowById.get(id);
+    if (row) acc.push(row);
+    return acc;
+  }, []);
+
+  selectedRows.forEach((row) => {
+    const assayKey = `${folderId}::${row.assay}`;
+    let assayNode = assayMap.get(assayKey);
+    if (!assayNode) {
+      assayNode = {
+        id: assayKey,
+        isAssayItem: true,
+        label: row.assay,
+        icon: "removeable",
+        children: [],
+        allExpAccessions: [],
+      };
+      assayMap.set(assayKey, assayNode);
+      root.children!.push(assayNode);
+    }
+
+    const ontologyKey = `${folderId}::${row.assay}-${row.ontology}`;
+    let ontologyNode = ontologyMap.get(ontologyKey);
+    if (!ontologyNode) {
+      ontologyNode = {
+        id: ontologyKey,
+        isAssayItem: false,
+        label: row.ontology,
+        icon: "removeable",
+        children: [],
+        allExpAccessions: [],
+      };
+      assayNode.children!.push(ontologyNode);
+      ontologyMap.set(ontologyKey, ontologyNode);
+    }
+
+    const displayNameKey = `${folderId}::${row.assay}-${row.ontology}-${row.displayName}`;
+    let displayNameNode = displayNameMap.get(displayNameKey);
+    if (!displayNameNode) {
+      displayNameNode = {
+        id: displayNameKey,
+        isAssayItem: false,
+        label: row.displayName,
+        icon: "removeable",
+        children: [],
+        allExpAccessions: [],
+      };
+      ontologyNode.children!.push(displayNameNode);
+      displayNameMap.set(displayNameKey, displayNameNode);
+    }
+
+    const expNode: TreeViewBaseItem<ExtendedTreeItemProps> = {
+      id: row.id,
+      isAssayItem: false,
+      label: formatIdLabel(row.id),
+      icon: "removeable",
+      assayName: row.assay,
+      children: [],
+      allExpAccessions: [row.id],
+    };
+    displayNameNode.children!.push(expNode);
+
+    assayNode.allExpAccessions!.push(row.id);
+    ontologyNode.allExpAccessions!.push(row.id);
+    displayNameNode.allExpAccessions!.push(row.id);
+  });
+
+  // standardize the order of the assay folders
+  root.children!.sort((a, b): number => {
+    const aAssay = a.id.split("::")[1] ?? a.id;
+    const bAssay = b.id.split("::")[1] ?? b.id;
+    return assayTypes.indexOf(aAssay) - assayTypes.indexOf(bAssay);
+  });
+
+  return [root];
+}
+
+/**
+ * Builds tree in the default view (sorted by ontology)
+ * Hierarchy: Ontology -> DisplayName -> Experiment
+ *
+ * @param selectedIds - list of selected row IDs
+ * @param rowById - Mapping between an id and its BiosampleRowInfo object
+ * @param rootLabel - Label for the root node
+ * @param folderId - Folder ID to prefix tree item IDs with
+ * @returns tree items for the RichTreeView
+ */
+export function buildTreeView(
+  selectedIds: string[],
+  rowById: Map<string, BiosampleRowInfo>,
+  rootLabel: string = "Biosamples",
+  folderId: string = "",
+): TreeViewBaseItem<ExtendedTreeItemProps>[] {
+  const root = createRootNode(rootLabel, folderId);
+  const ontologyMap = new Map<
+    string,
+    TreeViewBaseItem<ExtendedTreeItemProps>
+  >();
+  const displayNameMap = new Map<
+    string,
+    TreeViewBaseItem<ExtendedTreeItemProps>
+  >();
+
+  const selectedRows = selectedIds.reduce<BiosampleRowInfo[]>((acc, id) => {
+    const row = rowById.get(id);
+    if (row) acc.push(row);
+    return acc;
+  }, []);
+
+  selectedRows.forEach((row) => {
+    if (!row) {
+      return;
+    }
+    const ontologyKey = `${folderId}::${row.ontology}`;
+    let ontologyNode = ontologyMap.get(ontologyKey);
+    if (!ontologyNode) {
+      ontologyNode = {
+        id: ontologyKey,
+        label: row.ontology,
+        icon: "removeable",
+        children: [],
+        allExpAccessions: [],
+      };
+      ontologyMap.set(ontologyKey, ontologyNode);
+      root.children!.push(ontologyNode);
+    }
+
+    const displayNameKey = `${folderId}::${row.ontology}-${row.displayName}`;
+    let displayNameNode = displayNameMap.get(displayNameKey);
+    if (!displayNameNode) {
+      displayNameNode = {
+        id: displayNameKey,
+        label: row.displayName,
+        icon: "removeable",
+        children: [],
+        allExpAccessions: [],
+      };
+      ontologyNode.children!.push(displayNameNode);
+      displayNameMap.set(displayNameKey, displayNameNode);
+    }
+
+    const expNode: TreeViewBaseItem<ExtendedTreeItemProps> = {
+      id: row.id,
+      label: formatIdLabel(row.id),
+      icon: "removeable",
+      assayName: row.assay,
+      children: [],
+      allExpAccessions: [row.id],
+    };
+    displayNameNode.children!.push(expNode);
+
+    ontologyNode.allExpAccessions!.push(row.id);
+    displayNameNode.allExpAccessions!.push(row.id);
+  });
+
+  // standardize the order of the ontology folders
+  root.children!.sort((a, b): number => {
+    const aOntology = a.id.split("::")[1] ?? a.id;
+    const bOntology = b.id.split("::")[1] ?? b.id;
+    return ontologyTypes.indexOf(aOntology) - ontologyTypes.indexOf(bOntology);
+  });
+
+  return [root];
+}

package/src/TrackSelect/Folders/biosamples/shared/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Types for biosample folder data
+ */
+
+/**
+ * Assay information from the JSON data
+ */
+export type BiosampleAssayInfo = {
+  id: string;
+  assay: string;
+  url: string;
+  experimentAccession: string;
+  fileAccession: string;
+};
+
+/**
+ * Track information from the JSON data
+ */
+export type BiosampleTrackInfo = {
+  name: string;
+  ontology: string;
+  lifeStage: string;
+  sampleType: string;
+  displayName: string;
+  assays: BiosampleAssayInfo[];
+};
+
+/**
+ * Row format for DataGrid (flattened from TrackInfo)
+ */
+export type BiosampleRowInfo = {
+  id: string;
+  ontology: string;
+  lifeStage: string;
+  sampleType: string;
+  displayName: string;
+  assay: string;
+  experimentAccession: string;
+  fileAccession: string;
+  url: string;
+};
+
+/**
+ * Structure of the biosample JSON data files
+ */
+export type BiosampleDataFile = {
+  tracks: BiosampleTrackInfo[];
+};

package/src/TrackSelect/Folders/genes/data/human.json

@@ -0,0 +1,7 @@
+[
+  {
+    "id": "genocode-basic",
+    "displayName": "GENCODE Basic Genes",
+    "versions": [29, 40]
+  }
+]

package/src/TrackSelect/Folders/genes/data/mouse.json

@@ -0,0 +1,7 @@
+[
+  {
+    "id": "genocode-basic",
+    "displayName": "GENCODE Basic Genes",
+    "versions": [21, 25]
+  }
+]

package/src/TrackSelect/Folders/genes/human.ts

@@ -0,0 +1,16 @@
+import { createGeneFolder } from "./shared/createFolder";
+import humanData from "./data/human.json";
+import { GeneDataFile } from "./shared/types";
+
+/**
+ * Gene annotations folder for human (GRCh38 assembly)
+ *
+ * Contains gene annotation tracks like GENCODE that users can
+ * select to display in the genome browser.
+ */
+export const humanGenesFolder = createGeneFolder({
+  id: "human-genes",
+  label: "Genes",
+  description: "Gene annotation tracks",
+  data: humanData as GeneDataFile,
+});

package/src/TrackSelect/Folders/genes/mouse.ts

@@ -0,0 +1,16 @@
+import { createGeneFolder } from "./shared/createFolder";
+import mouseData from "./data/mouse.json";
+import { GeneDataFile } from "./shared/types";
+
+/**
+ * Gene annotations folder for human (GRCh38 assembly)
+ *
+ * Contains gene annotation tracks like GENCODE that users can
+ * select to display in the genome browser.
+ */
+export const mouseGenesFolder = createGeneFolder({
+  id: "mouse-genes",
+  label: "Genes",
+  description: "Gene annotation tracks",
+  data: mouseData as GeneDataFile,
+});

package/src/TrackSelect/Folders/genes/shared/columns.tsx

@@ -0,0 +1,42 @@
+import { GridColDef } from "@mui/x-data-grid-premium";
+import { GeneRowInfo } from "./types";
+
+/**
+ * Format versions array as comma-separated string with "v" prefix
+ * e.g., [29, 40] -> "v29, v40"
+ */
+function formatVersions(versions: number[]): string {
+  return versions.map((v) => `v${v}`).join(", ");
+}
+
+const displayNameCol: GridColDef<GeneRowInfo> = {
+  field: "displayName",
+  headerName: "Name",
+  flex: 1,
+  minWidth: 200,
+};
+
+const versionsCol: GridColDef<GeneRowInfo> = {
+  field: "versions",
+  headerName: "Versions",
+  width: 150,
+  valueFormatter: (value: number[]) => value && formatVersions(value),
+};
+
+/**
+ * Default columns for genes DataGrid (flat list, no grouping)
+ */
+export const defaultColumns: GridColDef<GeneRowInfo>[] = [
+  displayNameCol,
+  versionsCol,
+];
+
+/**
+ * No grouping for genes - flat list
+ */
+export const defaultGroupingModel: string[] = [];
+
+/**
+ * Leaf field - the unique identifier
+ */
+export const defaultLeafField = "id";

package/src/TrackSelect/Folders/genes/shared/createFolder.ts

@@ -0,0 +1,68 @@
+import { FolderDefinition } from "../../types";
+import { GeneDataFile, GeneRowInfo, GeneTrackInfo } from "./types";
+import {
+  defaultColumns,
+  defaultGroupingModel,
+  defaultLeafField,
+} from "./columns";
+import { buildTreeView } from "./treeBuilder";
+
+/**
+ * Transforms a single track from JSON into a row for DataGrid
+ * For genes, this is a 1:1 mapping (no flattening needed)
+ */
+function trackToRow(track: GeneTrackInfo): GeneRowInfo {
+  return {
+    id: track.id,
+    displayName: track.displayName,
+    versions: track.versions,
+  };
+}
+
+/**
+ * Transforms raw JSON data into rows and lookup map
+ */
+function transformData(data: GeneDataFile): {
+  rows: GeneRowInfo[];
+  rowById: Map<string, GeneRowInfo>;
+} {
+  const rows = data.map(trackToRow);
+  const rowById = new Map<string, GeneRowInfo>(
+    rows.map((row) => [row.id, row]),
+  );
+  return { rows, rowById };
+}
+
+export interface CreateGeneFolderOptions {
+  id: string;
+  label: string;
+  description?: string;
+  data: GeneDataFile;
+}
+
+/**
+ * Factory function that creates a FolderDefinition for genes
+ */
+export function createGeneFolder(
+  options: CreateGeneFolderOptions,
+): FolderDefinition<GeneRowInfo> {
+  const { id, label, description, data } = options;
+  const { rowById } = transformData(data);
+
+  return {
+    id,
+    label,
+    description,
+    rowById,
+    getRowId: (row) => row.id,
+
+    // Default view configuration
+    columns: defaultColumns,
+    groupingModel: defaultGroupingModel,
+    leafField: defaultLeafField,
+
+    // Tree builder for selected items panel
+    buildTree: (selectedIds, rowById) =>
+      buildTreeView(selectedIds, rowById, label),
+  };
+}

package/src/TrackSelect/Folders/genes/shared/treeBuilder.ts

@@ -0,0 +1,45 @@
+import { TreeViewBaseItem } from "@mui/x-tree-view";
+import { ExtendedTreeItemProps } from "../../../types";
+import { GeneRowInfo } from "./types";
+
+/**
+ * Builds a flat tree structure for the TreeView panel (selected items)
+ * Since genes have no grouping, this is a simple root -> leaf structure
+ *
+ * @param selectedIds - Array of selected row IDs
+ * @param rowById - Map of row ID to row data
+ * @param rootLabel - Label for the root node
+ * @returns Tree structure for RichTreeView
+ */
+export function buildTreeView(
+  selectedIds: string[],
+  rowById: Map<string, GeneRowInfo>,
+  rootLabel: string = "Genes",
+): TreeViewBaseItem<ExtendedTreeItemProps>[] {
+  // Root node
+  const root: TreeViewBaseItem<ExtendedTreeItemProps> = {
+    id: "root",
+    label: rootLabel,
+    icon: "folder",
+    children: [],
+    allExpAccessions: [],
+  };
+
+  // Get selected rows and add as direct children of root
+  selectedIds.forEach((id) => {
+    const row = rowById.get(id);
+    if (row) {
+      const leafNode: TreeViewBaseItem<ExtendedTreeItemProps> = {
+        id: row.id,
+        label: row.displayName,
+        icon: "removeable",
+        children: [],
+        allExpAccessions: [row.id],
+      };
+      root.children!.push(leafNode);
+      root.allExpAccessions!.push(row.id);
+    }
+  });
+
+  return [root];
+}

package/src/TrackSelect/Folders/genes/shared/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Types for genes folder data
+ */
+
+/**
+ * Gene track information from the JSON data
+ */
+export type GeneTrackInfo = {
+  /** Unique identifier for this gene track */
+  id: string;
+  /** Display name shown in the UI */
+  displayName: string;
+  /** Available versions for this gene annotation */
+  versions: number[];
+};
+
+/**
+ * Row format for DataGrid (same as track info for genes since it's flat)
+ */
+export type GeneRowInfo = {
+  id: string;
+  displayName: string;
+  versions: number[];
+};
+
+/**
+ * Structure of the gene JSON data files (direct array)
+ */
+export type GeneDataFile = GeneTrackInfo[];

package/src/TrackSelect/Folders/index.ts

@@ -0,0 +1,27 @@
+import { Assembly, FolderDefinition } from "./types";
+import { humanBiosamplesFolder } from "./biosamples/human";
+import { mouseBiosamplesFolder } from "./biosamples/mouse";
+import { humanGenesFolder } from "./genes/human";
+import { mouseGenesFolder } from "./genes/mouse";
+
+export {
+  type Assembly,
+  type FolderDefinition,
+  type FolderRuntimeConfig,
+} from "./types";
+
+/**
+ * Registry of folders available for each assembly.
+ *
+ * Each assembly can have multiple folders (e.g., biosamples, genes, etc.).
+ * TrackSelect receives the folders for the current assembly and renders
+ * them as tabs or a folder selector.
+ *
+ * To add a new folder:
+ * 1. Create a folder config file (e.g., folders/genes/human.ts)
+ * 2. Import and add it to the appropriate assembly array below
+ */
+export const foldersByAssembly: Record<Assembly, FolderDefinition[]> = {
+  GRCh38: [humanGenesFolder, humanBiosamplesFolder],
+  mm10: [mouseGenesFolder, mouseBiosamplesFolder],
+};

package/src/TrackSelect/Folders/types.ts

@@ -0,0 +1,95 @@
+import { GridColDef, GridRenderCellParams } from "@mui/x-data-grid-premium";
+import { TreeViewBaseItem } from "@mui/x-tree-view";
+import { ExtendedTreeItemProps, CustomTreeItemProps } from "../types";
+
+export type Assembly = "GRCh38" | "mm10";
+
+/**
+ * Runtime configuration that can be modified by ToolbarExtras components.
+ * This allows folder-specific UI (like AssayToggle) to dynamically update
+ * how the DataGrid displays data.
+ */
+export interface FolderRuntimeConfig {
+  columns: GridColDef[];
+  groupingModel: string[];
+  leafField: string;
+}
+
+/**
+ * Definition for a folder in TrackSelect.
+ *
+ * A folder represents a category of data (e.g., biosamples, genes, etc.)
+ * that can be displayed in the DataGrid and TreeView. Each folder is
+ * self-contained with its own data, column definitions, and tree building logic.
+ *
+ * @template TRow - The type of row data stored in this folder
+ */
+export interface FolderDefinition<TRow = any> {
+  /** Unique identifier for this folder */
+  id: string;
+
+  /** Display label shown in the UI */
+  label: string;
+
+  /** Optional description shown in folder cards */
+  description?: string;
+
+  /**
+   * Single source of truth for all row data.
+   * Maps row ID to the full row object.
+   */
+  rowById: Map<string, TRow>;
+
+  /**
+   * Function to extract the unique ID from a row object.
+   * Used for selection tracking and lookups.
+   */
+  getRowId: (row: TRow) => string;
+
+  /** Column definitions for the DataGrid */
+  columns: GridColDef[];
+
+  /** Fields to group by in the DataGrid (row grouping) */
+  groupingModel: string[];
+
+  /** The field that represents the leaf level in the grouping hierarchy */
+  leafField: string;
+
+  /**
+   * Builds a tree structure from selected row IDs.
+   * Used to display selected items in the TreeView panel.
+   *
+   * @param selectedIds - Array of selected row IDs
+   * @param rowById - Map of row ID to row data (same as this.rowById)
+   * @returns Array of tree items to render in the TreeView
+   */
+  buildTree: (
+    selectedIds: string[],
+    rowById: Map<string, TRow>,
+  ) => TreeViewBaseItem<ExtendedTreeItemProps>[];
+
+  /**
+   * Optional component to render folder-specific toolbar controls.
+   * For example, biosamples folder uses this to render an assay toggle
+   * that switches between sample-grouped and assay-grouped views.
+   *
+   * @param updateConfig - Callback to update the folder's runtime config
+   */
+  ToolbarExtras?: React.FC<{
+    updateConfig: (partial: Partial<FolderRuntimeConfig>) => void;
+  }>;
+
+  /**
+   * Optional custom component for rendering grouping cells in the DataGrid.
+   * If not provided, a default grouping cell renderer will be used.
+   */
+  GroupingCellComponent?: React.FC<GridRenderCellParams>;
+
+  /**
+   * Optional custom TreeItem component for the TreeView.
+   * If not provided, the default CustomTreeItem will be used.
+   */
+  TreeItemComponent?: React.ForwardRefExoticComponent<
+    CustomTreeItemProps & React.RefAttributes<HTMLLIElement>
+  >;
+}