pennsieve-dashboard 0.3.7 → 1.0.0

package/README.md

@@ -7,6 +7,21 @@
 
 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.
 
+---
+
+## Breaking Changes
+
+### v1.0.0 — `s3Url` and `apiUrl` removed from `dashboard:globalVars`
+
+The dashboard no longer provides `s3Url` or `apiUrl` as top-level properties in the injected `dashboard:globalVars` context. These values now live exclusively in `services` (e.g. `services.s3Url`, `services.ApiUrl`).
+
+**Widget libraries must update `useGlobalVars.ts`** to remove `s3Url`/`apiUrl` from `GlobalVarsShape` and read them from `services` instead.
+
+| PennsieveDashboard | SparcDashWidgets | PrecisionDashWidgets |
+|--------------------|------------------|----------------------|
+| >= 1.0.0           | >= 1.0.0         | >= 1.0.0             |
+
+Pre-1.0 versions of these packages are not compatible with 1.0+. If you're building a custom widget library, use the `services` pattern described in [Building a Component Library](#3-building-a-component-library).
 
 ---
 
@@ -58,131 +73,7 @@ Before you begin, ensure you have the following installed:
     # 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 
+3. Run
 ```
 npm run dev
 ```
@@ -251,16 +142,19 @@ Without these, the dashboard and widgets will not render correctly.
 
 #### 2. Available Widgets
 ```js
+import { markRaw } from ‘vue’
+
 const availableWidgets = [
-  { name: 'TextWidget', component: TextWidget },
-  { name: 'MarkdownWidget', component: MarkdownWidget }
+  { name: ‘TextWidget’, component: markRaw(TextWidget) },
+  { name: ‘MarkdownWidget’, component: markRaw(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.  
+- 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.
+- **Wrap components with `markRaw()`** to prevent Vue reactivity warnings. This is needed because Vue will attempt to make component objects reactive when they’re stored in reactive state (like `ref()` or `reactive()`), which is unnecessary and triggers console warnings. `markRaw()` tells Vue to skip reactivity for these objects.
 - You can extend this list with custom widgets or external widget libraries.  
 
 ---
@@ -308,6 +202,12 @@ const publicationStatus = computed(() => "foobar");
 const filesCount = computed(() => "b");
 const collaboratorCounts = computed(() => "a");
 
+const services = {
+  s3Url: "https://your-bucket.s3.amazonaws.com/your-data",
+  ApiUrl: "https://api.pennsieve.net",
+  // Add any other configurables your widgets need (API keys, endpoints, etc.)
+};
+
 const dashboardOptions = ref({
   globalData: {
     FileCount: filesCount.value,
@@ -316,12 +216,14 @@ const dashboardOptions = ref({
   },
   availableWidgets,
   defaultLayout,
+  services,
 });
 ```
 
-- **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.  
+- **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`.
+- **services**: key/value map of configurables (data URLs, API endpoints, API keys) that the dashboard provides to all widgets via `useDashboardGlobalVars().services`. Widgets read values like `services.s3Url` or `services.ScicrunchApiKey` from this object.
+- **dashboardOptions**: combines global data, available widgets, layout, and services into a single configuration object that powers the dashboard.  
 
 ---
 
@@ -387,7 +289,6 @@ When no URL parameters are present, behavior is unchanged — the dashboard uses
 
 ---
 
-## Contributing
 ## Contributing
 
 We welcome contributions from developers and the community. There are two main ways you can get involved:
@@ -397,52 +298,155 @@ If you encounter a bug, performance problem, or unexpected behavior in the dashb
 - 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.  
+### 2. Adding a Custom Component to an Existing Widget Library
 
-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).
+Each widget library (e.g. SparcDashWidgets, PrecisionDashWidgets) follows the same component convention. Below is a real-world example — the **BiolucidaViewer** from SparcDashWidgets — showing how a component connects to the dashboard’s shared state via `useDashboardGlobalVars()`.
 
-#### Sample Component
-Here’s a minimal example of a custom widget component:
-
-```
-//vue
+```vue
 <template>
-  <!-- Child icons show up in the widget header -->
+  <!-- Scoped slot exposes the widget name and header icons to the dashboard shell -->
   <slot :widgetName="widgetName" :childIcons="childIcons"></slot>
 
-  <div class="my-widget-name-wrap" v-bind="$attrs">
-    <!-- Component body goes here -->
+  <div v-bind="$attrs" class="tw-flex tw-flex-col">
+    <div v-if="selectedImage" class="bv-metadata">
+      <div><b>Sex:</b> {{ selectedImage.sex }}</div>
+      <div><b>Age:</b> {{ selectedImage.ageRange }}</div>
+      <div><b>Sample Path:</b> {{ selectedImage.relativePath }}</div>
+    </div>
+    <div class="tw-h-screen tw-flex tw-justify-center">
+      <iframe class="tw-p-1 tw-w-screen" :src="biolucidaPath"></iframe>
+    </div>
   </div>
 </template>
 
-<script setup lang="ts">
-import { ref, watch, computed, shallowRef } from 'vue'
-import { Edit } from '@element-plus/icons-vue'
+<script setup>
+import { ref, computed, watch, shallowRef } from "vue";
+import { useDashboardGlobalVars } from ‘../../useGlobalVars’
+import { InfoFilled } from "@element-plus/icons-vue";
+
+const widgetName = ref(‘MBF Image Viewer’);
+const childIcons = shallowRef([
+  { comp: InfoFilled, tooltip: "Lock Biolucida Viewer" }
+]);
 
-defineOptions({ inheritAttrs: false })
+const props = defineProps({
+  imageID: 0,
+  isLocked: { default: false, type: Boolean }
+});
 
-// Props can be passed in from the defaultLayout in dashboard options or set programmatically.
-const props = defineProps<{
-  property1?: string
-}>()
+// Access the dashboard’s injected global vars (services, filters, etc.)
+const GlobalVars = useDashboardGlobalVars();
 
-const emit = defineEmits<{
-  (e: 'updateComponent', value: string): void
-}>()
+// Read a filter value reactively
+const selectedImage = computed(() => {
+  return GlobalVars?.filters?.SELECTED_IMAGE;
+});
 
-// 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' }
-])
+const biolucidaPath = ref("");
 
-function toggleMode() {
-  // Custom code for toggling edit mode
-}
+watch(selectedImage, (newVal, oldVal) => {
+  if (newVal?.biolucidaID !== oldVal?.biolucidaID) {
+    biolucidaPath.value = `https://sparc.biolucida.net/image?c=${newVal?.biolucidaID}`;
+  }
+}, { immediate: true });
 </script>
 ```
 
+The key takeaway: call `useDashboardGlobalVars()` in your component to access the dashboard’s shared state — `services` (data URLs, API keys), `filters`, and filter-setting methods — without any extra wiring. See the [Building a Component Library](#3-building-a-component-library) section below for a full explanation of this composable.
+
+---
+
+### 3. Building a Component Library
+
+If you’re building a **new widget library** (rather than adding to an existing one), you need to understand how the PennsieveDashboard communicates with widget components.
+
+#### How the Dashboard Provides Context
+
+When the `PennsieveDashboard` component mounts, it calls `provide("dashboard:globalVars", ...)` to inject a shared context object into the component tree. Any descendant component — including widgets from external libraries — can access this context using Vue’s `inject`.
+
+#### The `useGlobalVars.ts` Composable
+
+To access the injected context, your library should include a `useGlobalVars.ts` file (you can copy this directly from [SparcDashWidgets](https://github.com/nih-sparc/SparcDashWidgets)):
+
+```ts
+// src/useGlobalVars.ts
+import { inject } from ‘vue’
+
+export const DASHBOARD_GLOBAL_VARS_KEY = ‘dashboard:globalVars’ as const
+export type FilterValue = string | number | boolean | null | string[] | number[]
+export type Filters = Record<string, FilterValue>
+export type Services = Record<string, any>
+
+export type GlobalVarsShape = {
+  services: Services | import(‘vue’).Ref<Services>  // All configurables (URLs, API keys, etc.)
+  filters: Filters | import(‘vue’).Ref<Filters>     // Shared reactive filter state
+  setFilter: (key: string, value: FilterValue, isDisplayed?: boolean) => void
+  clearFilter: (key: string) => void
+  resetFilters?: (next?: Filters) => void
+}
+
+export function useDashboardGlobalVars(required = false) {
+  const gv = inject<GlobalVarsShape | null>(DASHBOARD_GLOBAL_VARS_KEY, null)
+  if (!gv && required) {
+    console.warn(‘[Widget] dashboard:globalVars not provided.’)
+  }
+  return gv
+}
+```
+
+#### What Each Property Does
+
+| Property | Description |
+|----------|-------------|
+| `services` | Key-value map of configurables passed in from the host application — data URLs, API endpoints, API keys, etc. For example: `services.s3Url`, `services.ApiUrl`, `services.ScicrunchApiKey`. |
+| `filters` | Reactive key-value object representing the current dashboard filter state. Widgets read from this to stay in sync. |
+| `setFilter(key, value, isDisplayed?)` | Set a filter value. `isDisplayed` controls whether the filter chip appears in the dashboard header. |
+| `clearFilter(key)` | Remove a single filter by key. |
+| `resetFilters(next?)` | Clear all filters, optionally replacing them with `next`. |
+
+#### Using Filters for Cross-Widget Communication
+
+Filters are the primary mechanism for widgets to communicate. One widget sets a filter, and other widgets react to the change:
+
+```ts
+const GlobalVars = useDashboardGlobalVars();
+
+// Read a service configurable (e.g. data URL, API key)
+const dataUrl = unref(GlobalVars?.services)?.s3Url;
+const apiKey = unref(GlobalVars?.services)?.ScicrunchApiKey;
+
+// Set a filter (other widgets will see this reactively)
+GlobalVars?.setFilter(‘SELECTED_GENE’, ‘CDH9’, true);
+
+// Read a filter
+const gene = GlobalVars?.filters?.SELECTED_GENE;
+
+// Clear a filter
+GlobalVars?.clearFilter(‘SELECTED_GENE’);
+
+// Reset all filters
+GlobalVars?.resetFilters();
+```
+
+#### Library Structure
+
+A typical widget library follows this structure:
+
+```
+your-widget-library/
+├── src/
+│   ├── components/          # Widget components (public API)
+│   │   ├── MyWidget/
+│   │   │   └── MyWidget.vue
+│   │   └── index.js         # Barrel export
+│   ├── useGlobalVars.ts     # Copy from SparcDashWidgets
+│   └── main.ts              # Dev entry point
+├── package.json
+└── vite.config.ts           # Build in library mode
+```
+
+Your `vite.config.ts` should build in library mode with `vue`, `pinia`, and `element-plus` as externals. See SparcDashWidgets or PrecisionDashWidgets for working examples.
+
 ## Contact Support
 
 There are several ways to get in contact with our support team.