Repository navigation
3.3 Home Page Library UI and Dialogs
Relevant source files
The following files were used as context for generating this wiki page:
This page covers section 3.3 of the VariantScope wiki, detailing the home page UI, the saved gene library management, folder organization, drag-and-drop mechanics, confirmation interaction patterns, the native modal dialog infrastructure, and DOM construction helpers.
The home page interface functions as the central landing point of VariantScope (src/index.html lines 44–78). It displays an introductory explanation, an interactive saved gene library (#library), folder toolbars, storage quotas, and gene grid cards (#home-list).
UI modules interact with core data structures (src/core/library.js, src/core/folders.js) to render user-saved genes and organize them hierarchically. All user-facing DOM nodes are constructed via secure programmatic helpers (src/ui/dom.js) to adhere to strict Content Security Policy (CSP) guidelines, avoiding innerHTML execution or inline style injections.
+-----------------------------------------------------------------+
| src/index.html |
| +--------------------+ +----------------------+ |
| | #welcome (Home) |-------------->| src/ui/home.js | |
| | - Empty state | | - geneCard() | |
| | - Library grid | | - confirmButton() | |
| | - Folder toolbar | | - Drag-and-Drop | |
| +--------------------+ +----------------------+ |
| | |
| +------------+------------+
| v v
| +--------------------------+ +-------------------+
| | src/ui/dialog.js | | src/ui/dom.js |
| | - Native <dialog> wrapper| | - el() / fill() |
| | - Focus trap & Esc close| | - clear() |
| +--------------------------+ +-------------------+
+-----------------------------------------------------------------+
Sources: src/index.html:44-78, src/ui/home.js:1-18, src/ui/dialog.js:1-8, src/ui/dom.js:1-5
2. DOM Helper Utilities (src/ui/dom.js)
To prevent script injection vulnerabilities and comply with strict CSP configurations, VariantScope forbids arbitrary HTML string parsing. Instead, all dynamic elements are instantiated via functional DOM helpers.
-
el(tag, props = {}, ...children): Instantiates a DOM element of typetag, assigns attributes, processes classes, binds event listeners prefixed withon(case-insensitive), updates dataset properties, and appends valid child nodes (src/ui/dom.js:5-19). -
fill(node, ...children): Safely replaces the children of a target node, filtering outnull,undefined, andfalsevalues (src/ui/dom.js:21-27). -
clear(node): Resets a node's content by invokingnode.replaceChildren()(src/ui/dom.js:29-32). -
externalLink(href, text, label): Generates safe external anchor tags configured withtarget="_blank",rel="noopener noreferrer", and an internal dataset flag (src/ui/dom.js:34-44).
+-----------------------------------------------------------------------+
| DOM Construction & Safety Flow |
| |
| API Data / State ----> el(tag, props, children) |
| | |
| +----------------+----------------+ |
| | key === 'class' | key startsWith 'on' |
| v v |
| node.className addEventListener |
| | | |
| +----------------+----------------+ |
| v |
| Append flattened, non-null children |
| v |
| Safe DOM Node Ready |
+-----------------------------------------------------------------------+
Sources: src/ui/dom.js:1-45
3. Modal Dialog Infrastructure (src/ui/dialog.js)
src/ui/dialog.js implements a lightweight modal dialog wrapper utilizing the native HTML <dialog> element (src/ui/dialog.js:1-38).
-
Focus Trapping & Escape Handling: Native
<dialog>elements handle focus management andEsckey interception automatically viadialog.showModal()(src/ui/dialog.js:36). -
Asynchronous Action Handlers: Actions mapped via
openDialog({ title, body, actions, opener })accept async callbacks. If an action'sonClickreturnsfalse(e.g., validation failure on a folder name), the dialog remains open (src/ui/dialog.js:5-18). -
Focus Restoration: Upon closing or cancellation, focus is restored to the triggering element specified by
opener(src/ui/dialog.js:31-34).
Sources: src/ui/dialog.js:1-39
4. Library UI and Gene Cards (src/ui/home.js)
The library UI translates saved gene metadata into grid cards (src/ui/home.js:48-114). Each card summarizes analytical metrics and provides control triggers.
Each card displays:
-
Header: Gene symbol and badges indicating outdated cache status (
badge-outdated) or partial download state (badge-partial) (src/ui/home.js:71-77). -
Metadata: Protein name, saved time age (
formatAge), analyzed variant counts (formatCount), pathogenic variant share percentage, and storage footprint (formatBytes) (src/ui/home.js:50-59, 78-79). - Action Bar: Buttons for Open, Refresh, Folders (desktop app only), and a two-step confirmation Delete button (src/ui/home.js:81-112).
+-----------------------------------------------------------------------+
| Gene Card Component |
| +-----------------------------------------------------------------+ |
| | BRCA1 [Out of date] | |
| | Breast cancer type 1 susceptibility protein | |
| | - Saved 2 days ago | |
| | - 1,420 variants analysed | |
| | - 14.5% pathogenic or likely pathogenic | |
| | - Size: 1.2 MB | |
| | | |
| | [ Open ] [ Refresh ] [ Folders... ] [ Delete ] | |
| +-----------------------------------------------------------------+ |
+-----------------------------------------------------------------------+
Sources: src/ui/home.js:48-114
Destructive actions such as deleting a saved gene employ a two-step confirmation button to prevent accidental data loss (src/ui/home.js:23-45).
+-------------------+ First Click +-----------------------+
| Label: "Delete" |---------------------->| Label: "Click again" |
| Timer: null | | Timer: 4s active |
+-------------------+ +-----------------------+
^ |
| Timeout / Reset | Second Click
+----------------------------------------------+--------------+
| v |
| Execute `onConfirm()` |
+-------------------------------------------------------------+
-
First Click: The button text swaps to the confirmation label (
confirmLabel), and a 4-second timeout is scheduled (src/ui/home.js:31-37). -
Second Click (Within 4s): Clears the timeout and executes the
onConfirmcallback (src/ui/home.js:39-42). - Timeout Expiry: Reverts the button label to its original state (src/ui/home.js:33-36).
Sources: src/ui/home.js:23-45
In desktop (Electron) deployments, the library supports hierarchical folder organization and drag-and-drop operations for genes and folders (src/ui/home.js:116-158).
-
startDrag: Sets the globaldraggingreference payload, specifies move effects, and populatesdataTransferpayloads with gene symbols or folder IDs (src/ui/home.js:119-124). -
canDrop: Validates whether a dragged item can be dropped onto a target folder (preventing self-nesting loops or redundant moves) via core helper functions likefolderMoveError(src/ui/home.js:134-138). -
makeDropTarget: Listens todragover,dragleave, anddropevents on folder cards and breadcrumb items, applying CSS highlights (drop-target) and invoking view movement handlers (view.onMoveGeneorview.onMoveFolder) (src/ui/home.js:141-157). -
endDrag: Resets drag states and purges DOM drop target classes (src/ui/home.js:127-131).
+-----------------------------------------------------------------+
| Drag-and-Drop & Folder Architecture |
| |
| [Gene / Folder Card] |
| | |
| v (ondragstart) |
| startDrag(event, payload) ---> sets global `dragging` |
| | |
| v (ondragover / drop) |
| canDrop(view, targetId) ---> validates target via core rules |
| | |
| v |
| view.onMoveGene() / view.onMoveFolder() |
+-----------------------------------------------------------------+
Sources: src/ui/home.js:116-158, docs/screenshots/electron-home.png, docs/screenshots/electron-folders.png
Sources: src/index.html, src/ui/home.js, src/ui/dialog.js, src/ui/dom.js, docs/screenshots/electron-home.png, docs/screenshots/electron-folders.png
Content imported from DeepWiki.