pennsieve-dashboard 0.2.1 → 0.2.3

package/README.md

@@ -1,5 +1,418 @@
 # Vue 3 + TypeScript + Vite
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+# PennsieveDashboard
 
-Learn more about the recommended Project Setup and IDE Support in the [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).
+[![Latest Build NPM](https://www.npmjs.com/package/pennsieve-dashboard)]()  
+[![This Repo Is Part of the Pennsieve Platform](https://app.pennsieve.io)]()
+
+The **PennsieveDashboard** is a web application that provides a user interface for interacting with Pennsieve data, visualizing metrics, and managing dashboards relevant to scientific datasets.
+
+
+---
+
+## Table of Contents
+
+- [Features](#features)  
+- [Getting Started](#getting-started)  
+  - [Prerequisites](#prerequisites)  
+  - [Installation](#installation)  
+- [Usage](#usage)  
+
+- [Contributing](#contributing)  
+- [Contact / Support](#contact-support)
+
+---
+
+## Features
+
+- Dashboard views for Pennsieve, Sparc, and Percision  
+- Visual metrics and charts (e.g. usage, growth)  
+- Authentication and role-based access  
+- Publishing and versioning support  
+- Tag filtering and search  
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+- [Node.js](https://nodejs.org/) (version ≥ 14)  
+- npm or Yarn
+- Element Plus (^2.11.0)
+- Pinia (^3.0.3)
+
+### Installation
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/Pennsieve/PennsieveDashboard.git
+   cd PennsieveDashboard
+
+2. Install
+    ```
+    npm install
+    # or
+    yarn install
+    ```
+3. App.vue
+For install and testing copy and paste this into your App.vue
+
+```
+//App.vue
+<script setup>
+import { computed, ref } from 'vue';
+import {PennsieveDashboard, MarkdownWidget, TextWidget} from 'pennsieve-dashboard'
+import 'element-plus/dist/index.css';
+import 'pennsieve-dashboard/style.css'
+
+/*
+Computed
+*/
+const publicationStatus = computed(() => {
+  return "foobar"
+});
+
+const filesCount = computed(() => {
+  return "b"
+});
+
+const collaboratorCounts = computed(()=>{
+  return "a"
+})
+
+
+const availableWidgets = [
+  //name must match componentKey
+  { name: 'TextWidget', component: TextWidget },
+  {name:'MarkdownWidget',component:MarkdownWidget}
+]
+const defaultLayout = [
+        {
+          id: 'MarkdownWidget-6',
+          x: 0, y: 0, w: 3, h: 9,
+          componentKey: 'MarkdownWidget',
+          componentName: 'Markdown Widget',
+          component: MarkdownWidget,   
+          Props:{
+            markdownText:[
+          '# Human DRG Dataset Dashboard',
+          '',
+          'This is a dashboard associated with the **NIH HEAL PRECISION Human Pain** consortium project. It aggregates data from several U19 centers in a standardized way. Using the different widgets, you can view, query and export the data in various ways:',
+          '',
+          '## Widgets',
+          '',
+          '### UMAP Viewer',
+          'This widget provides the UMAP representation of the entire dataset, you can select the color mapping based on different metadata elements.',
+          '',
+          '### The Data Explorer',
+          'Directly query over the data using SQL and export the results as a CSV file.',
+          '',
+          '### Proportion Viewer',
+          'Explore metrics between the different datasets that comprise the aggregated data.'
+        ].join('\n')
+          }
+        },
+        { 
+          id: "TextWidget-1", 
+          x: 0, y: 0, h: 1, w:4, 
+          componentName:"Text",
+          componentKey:"TextWidget",
+          component:TextWidget,
+          hideHeader:true, 
+          Props:{displayText:"Dataset Overview",hideHeader:true}
+        },
+        { 
+          id: "TextWidget-2", 
+          x: 0, y: 1, h: 2, w:1, 
+          componentName:"Files",
+          componentKey:"TextWidget",
+          component:TextWidget,
+          Props:{bindedKey:"FileCount"} 
+        },
+        { 
+          id: "TextWidget-3", 
+          x: 1, y: 1, h: 2, w:2, 
+          componentName:"Status",
+          componentKey:"TextWidget",
+          component:TextWidget,
+          Props:{bindedKey:"Status"}
+        },
+        { 
+          id: "TextWidget-4", 
+          x: 3, y: 1, h: 2, w:2, 
+          componentName:"Collaborator Counts",
+          componentKey:"TextWidget",
+          component:TextWidget,
+          Props:{bindedKey:"CollaboratorCounts"}
+        }
+      ]
+
+const dashboardOptions = ref({
+  globalData: {
+    FileCount: filesCount.value,
+    Status: publicationStatus.value,
+    CollaboratorCounts: collaboratorCounts.value
+  },
+  availableWidgets,
+  defaultLayout,
+})
+
+</script>
+<template>
+      <PennsieveDashboard class="dashboard-app" :options="dashboardOptions"></PennsieveDashboard>
+
+</template>
+
+<style scoped>
+/* set style vars from outside the dashboard > customize to match your application */
+.dashboard-app{
+    --el-color-primary: #243d8e;
+    --el-color-primary-light-3: #fbfdff;
+    --el-color-primary-dark-2: #546085;
+    --color:#243d8e;
+    --el-dialog-width: 90%;
+    --dash-secondary: #243d8e;
+  }
+
+</style>
+
+```
+
+4. Run 
+```
+npm run dev
+```
+## Usage
+## Using the Dashboard and Widgets
+
+The **Pennsieve Dashboard** can be used in two ways:
+
+1. **Standalone** – with its built-in widgets.  
+2. **Extended** – by integrating with external widget libraries, such as the [SPARC Widgets Library](https://github.com/nih-sparc/SparcDashWidgets).  
+   - You can see a demo of the SPARC dashboard in action here: [SPARC Dashboard Demo](https://staging.sparc.science/apps/sparc-dashboard).
+
+---
+
+### Built-in Widgets
+
+The dashboard ships with a small set of widgets out of the box. These can be used immediately to create dashboards without adding external libraries.
+
+- **Markdown Widget**  
+  Displays formatted text using Markdown syntax. Useful for adding documentation, context, or descriptive notes directly in the dashboard.  
+
+- **Text Widget**  
+  Displays plain or bound text values (e.g., counts, statuses, labels). Useful for lightweight metrics and quick information displays.  
+
+---
+
+### Adding Widgets to the Dashboard
+
+Widgets are registered in the `availableWidgets` array, and their default layout is defined in the `defaultLayout` configuration. Each widget requires:
+
+- A unique `id`
+- Position and size (`x`, `y`, `w`, `h`)
+- `componentKey` (must match the widget’s registration name)
+- `componentName`
+- Props (e.g., `displayText`, `markdownText`, `bindedKey`)
+
+---
+
+### Example: Embedding the Dashboard in Your Application
+
+The following example shows how to embed the **Pennsieve Dashboard** into a Vue 3 application.  
+The example is broken down into six key parts so developers can understand how each piece works and how to extend it.
+
+---
+
+
+#### 1. Imports
+```js
+import { computed, ref } from 'vue';
+import { PennsieveDashboard, MarkdownWidget, TextWidget } from 'pennsieve-dashboard';
+import 'element-plus/dist/index.css';
+import 'pennsieve-dashboard/style.css';
+```
+
+- **Vue imports**:  
+  - `ref` – for reactive state.  
+  - `computed` – for derived or dynamic values you want to expose to widgets.  
+- **Dashboard & widgets**: import the core `PennsieveDashboard` component along with any widgets you want to use (in this case, `MarkdownWidget` and `TextWidget`).  
+- **Styles**:  
+  - `element-plus/dist/index.css` – required styles for the Element Plus UI library.  
+  - `pennsieve-dashboard/style.css` – base dashboard styling.  
+
+Without these, the dashboard and widgets will not render correctly.
+
+---
+
+#### 2. Available Widgets
+```js
+const availableWidgets = [
+  { name: 'TextWidget', component: TextWidget },
+  { name: 'MarkdownWidget', component: MarkdownWidget }
+];
+```
+
+- This array **registers which widgets the dashboard can use**.  
+- Each widget entry must define:  
+  - `name` – must match the widget’s `componentKey` in the layout.  
+  - `component` – the imported Vue component.  
+- You can extend this list with custom widgets or external widget libraries.  
+
+---
+
+#### 3. Default Layout
+```js
+const defaultLayout = [
+  {
+    id: 'MarkdownWidget-6',
+    x: 0, y: 0, w: 3, h: 9,
+    componentKey: 'MarkdownWidget',
+    componentName: 'Markdown Widget',
+    component: MarkdownWidget,
+    Props: {
+      markdownText: "# Human DRG Dataset Dashboard\n..."
+    }
+  },
+  {
+    id: "TextWidget-1",
+    x: 0, y: 0, h: 1, w: 4,
+    componentName: "Text",
+    componentKey: "TextWidget",
+    component: TextWidget,
+    hideHeader: true,
+    Props: { displayText: "Dataset Overview" }
+  }
+  // additional TextWidget entries...
+];
+```
+
+- Controls **how widgets are arranged on the grid**.  
+- Each widget requires:  
+  - `id` – unique identifier for the widget instance.  
+  - `x, y, w, h` – grid position and size.  
+  - `componentKey` – must match the `name` from `availableWidgets`.  
+  - `componentName` – display label for the widget.  
+  - `Props` – configuration for the widget (text content, markdown, or bound keys).  
+- Developers can define multiple widgets and fine-tune their placement.  
+
+---
+
+#### 4. Dashboard Options
+```js
+const publicationStatus = computed(() => "foobar");
+const filesCount = computed(() => "b");
+const collaboratorCounts = computed(() => "a");
+
+const dashboardOptions = ref({
+  globalData: {
+    FileCount: filesCount.value,
+    Status: publicationStatus.value,
+    CollaboratorCounts: collaboratorCounts.value
+  },
+  availableWidgets,
+  defaultLayout,
+});
+```
+
+- **Computed values**: hold live data you want to expose inside the dashboard. These could come from an API call or another reactive source.  
+- **globalData**: key/value pairs accessible to widgets. For example, a `TextWidget` can bind to `FileCount` or `Status`.  
+- **dashboardOptions**: combines global data, available widgets, and layout into a single configuration object that powers the dashboard.  
+
+---
+
+#### 5. Template
+```vue
+<template>
+  <PennsieveDashboard class="dashboard-app" :options="dashboardOptions" />
+</template>
+```
+
+- Renders the `PennsieveDashboard` component.  
+- The `:options` prop passes in the configuration created above.  
+- Any widget defined in `defaultLayout` will be rendered automatically.  
+
+---
+
+#### 6. Styles
+```css
+<style scoped>
+.dashboard-app {
+  --el-color-primary: #243d8e;
+  --el-color-primary-light-3: #fbfdff;
+  --el-color-primary-dark-2: #546085;
+  --color: #243d8e;
+  --el-dialog-width: 90%;
+  --dash-secondary: #243d8e;
+}
+</style>
+```
+
+- Dashboard styling can be overridden using **CSS variables**.  
+- Customize colors, spacing, and UI elements to match your application’s theme.
+
+## Contributing
+## Contributing
+
+We welcome contributions from developers and the community. There are two main ways you can get involved:
+
+### 1. Reporting Bugs or Issues
+If you encounter a bug, performance problem, or unexpected behavior in the dashboard:
+- Please report it through the official support channels.
+- Include as much detail as possible (steps to reproduce, screenshots, browser/OS version, etc.) so we can investigate and resolve quickly.
+
+### 2. Building Custom Widget Libraries
+The dashboard is designed to be extensible. Developers can build their own widget libraries and plug them into the dashboard.  
+
+For reference, check out the [SPARC Dash Widgets Library](https://github.com/nih-sparc/SparcDashWidgets), which provides an example of how to build custom widgets. You can also see it in action at the [SPARC Dashboard Demo](https://staging.sparc.science/apps/sparc-dashboard).
+
+#### Sample Component
+Here’s a minimal example of a custom widget component:
+
+```
+//vue
+<template>
+  <!-- Child icons show up in the widget header -->
+  <slot :widgetName="widgetName" :childIcons="childIcons"></slot>
+
+  <div class="my-widget-name-wrap" v-bind="$attrs">
+    <!-- Component body goes here -->
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch, computed, shallowRef } from 'vue'
+import { Edit } from '@element-plus/icons-vue'
+
+defineOptions({ inheritAttrs: false })
+
+// Props can be passed in from the defaultLayout in dashboard options or set programmatically.
+const props = defineProps<{
+  property1?: string
+}>()
+
+const emit = defineEmits<{
+  (e: 'updateComponent', value: string): void
+}>()
+
+// Provide values for your scoped slot so it doesn't error
+const widgetName = 'example widget'
+const childIcons = shallowRef([
+  { comp: Edit, event: toggleMode, tooltip: 'click to open edit mode' }
+])
+
+function toggleMode() {
+  // Custom code for toggling edit mode
+}
+</script>
+```
+
+## Contact Support
+
+There are several ways to get in contact with our support team. 
+**support page**
+https://discover.pennsieve.io/about/support