Merge pull request #113 from sbv-world-health-org-metrics/docs

Add documentation page and banner to new users

who-metrics-ui/docs/definitions.md

@@ -0,0 +1,27 @@
+## Welcome to the Open-Source Metrics Documentation
+
+#### How to Read World Health Organization Open-Source Dashboard
+
+The Dashboard is currently a snapshot of data from the **World Organization Health** Repositories. All the metrics are based on the _Last Updated Date_ reflected on the top of the dashboard.
+
+### Metrics and Definitions
+
+`Collaborators:` Collaborator is an individual that can read a write to the current repository. Metric calculates the current number of Collaborators.
+
+`Watchers:` The number of users who are tracking a particular repository, receiving notifications regarding its activity.
+
+`Open Issues:` Issues are tickets that represent bugs or new features that other people report and can collaborate on. Open issues are total of unresolved issues.
+
+`Open PR's:` A pull request is a request to make a change to the files of the project (code, documentation, README changes, etc.). Open PR's are the total of pull requests with status Open.
+
+`Merge PR's`: A total of Pull Requests that are accepted into the code base of the project.
+
+`Total Fork:` A fork is a copy of the current repository belonging to another user. Total Forks is how many times the repository has been copied.
+
+`Open Issues Median Age:` Median of how many days of all issues in days with Open Status. If the issue age is zero (meaning there are no open issues), we display "N/A".
+
+`Close Issues Median Age:` Median of how many days of all issues in days with Closed status. If the issue age is zero (meaning there are no open issues), we display "N/A".
+
+`Issue Response Median Age:` Median response time of issues that has a response. If the issue response age is zero (meaning there are no comments), we display "N/A". If the first response is by the creator of the issue the comment is not counted.
+
+`Issue Response Average Age:` Average response time of issues that has a response. If the issue response age is zero (meaning there are no comments), we display "N/A". If the first response is by the creator of the issue the comment is not counted. Calculation is Issues Total Response Time divide by Total Issues

who-metrics-ui/next.config.js

@@ -2,13 +2,21 @@
 const nextConfig = {
   reactStrictMode: true,
   productionBrowserSourceMaps: true,
+  pageExtensions: ['js', 'jsx', 'mdx', 'ts', 'tsx', 'json'],
   basePath:
     process.env.NODE_ENV === "development"
       ? ""
       : "/sbv-world-health-org-metrics",
   images: {
     unoptimized: true,
   },
+  webpack: (config) => {
+    config.module.rules.push({
+      test: /\.md$/,
+      use: "raw-loader",
+    });
+    return config;
+  }
 };
 
-module.exports = nextConfig;
+module.exports = nextConfig

who-metrics-ui/package.json

@@ -11,9 +11,9 @@
   "dependencies": {
     "@headlessui/react": "^1.7.12",
     "@heroicons/react": "^2.0.16",
-    "@planetscale/database": "^1.5.0",
     "@primer/octicons-react": "^19.4.0",
     "@primer/react": "^35.26.0",
+    "@tailwindcss/typography": "^0.5.10",
     "@tremor/react": "^3.3.0",
     "@types/js-cookie": "^3.0.3",
     "@types/node": "18.15.11",
@@ -27,19 +27,22 @@
     "json-2-csv": "^5.0.1",
     "kysely": "^0.23.4",
     "kysely-planetscale": "^1.3.0",
+    "marked": "^12.0.1",
     "next": "^13.5.6",
     "next-auth": "^4.24.5",
     "next-themes": "^0.2.1",
     "postcss": "^8.4.31",
     "prop-types": "^15.8.1",
+    "raw-loader": "^4.0.2",
     "react": "^18.2.0",
     "react-data-grid": "^7.0.0-beta.41",
     "react-dom": "^18.2.0",
     "react-tiny-popover": "^8.0.4",
     "server-only": "^0.0.1",
     "styled-components": "^5.3.11",
     "tailwindcss": "^3.2.7",
-    "typescript": "4.9.5"
+    "typescript": "4.9.5",
+    "usehooks-ts": "^3.0.1"
   },
   "homepage": "https://sbv-world-health-org-metrics.github.io/sbv-world-health-org-metrics/",
   "devDependencies": {

who-metrics-ui/src/components/Documentation.tsx

@@ -0,0 +1,18 @@
+import { marked } from 'marked'
+import docs from '../../docs/definitions.md'
+
+const convertMarkdownToHTML = (markdown: string): string => {
+  return marked(markdown) as string
+}
+
+const Documentation = () => {
+  const html = convertMarkdownToHTML(docs)
+
+  return (
+    // eslint-disable-next-line react/no-danger
+    <div dangerouslySetInnerHTML={{ __html: html }} />
+  )
+}
+
+
+export default Documentation

who-metrics-ui/src/components/OrganizationSheet.tsx

@@ -1,5 +1,7 @@
 'use client';
 
+import { useLocalStorage } from 'usehooks-ts';
+
 import {
   Tab,
   TabGroup,
@@ -11,14 +13,24 @@ import {
 } from '@tremor/react';
 
 import logo from '@/images/who-logo-wide.svg';
-import { Box, useTheme as primerUseTheme } from '@primer/react';
+import {
+  Box,
+  Flash,
+  IconButton,
+  useTheme as primerUseTheme
+} from '@primer/react';
 import Image from 'next/image';
 
+import { useIsSSR } from '@/hooks/useIsSSR';
+import { XIcon } from '@primer/octicons-react';
 import { useTheme } from 'next-themes';
 import data from '../data/data.json';
+import Documentation from './Documentation';
 import RepositoriesTable from './RepositoriesTable';
 
 export const OrganizationSheet = () => {
+  const [showBanner, setShowBanner] = useLocalStorage('show-banner', false);
+  const isSSR = useIsSSR();
   const { theme, systemTheme } = useTheme();
   const { setColorMode } = primerUseTheme();
   if (theme === 'light' || theme === 'dark' || theme === 'auto') {
@@ -48,14 +60,43 @@ export const OrganizationSheet = () => {
         This project includes metrics about the Open Source repositories for the
         {data.orgInfo.name}.
       </Text>
+      {!isSSR && showBanner && (
+        <Box className="mt-6">
+          <Flash
+            variant="default"
+            sx={{
+              display: 'flex',
+              justifyContent: 'space-between',
+              alignItems: 'center',
+            }}
+          >
+            <Box>Open Source Health Metrics for <span className='font-semibold'>{data.orgInfo.name}</span>. Visit the Documentation page to learn more about how these metrics are calcultated.</Box>
+            <Box>
+              <IconButton
+                onClick={() => setShowBanner(false)}
+                variant="invisible"
+                icon={XIcon}
+                aria-label="Dismiss"
+                sx={{ svg: { margin: '0', color: 'fg.muted' } }}
+              />
+            </Box>
+          </Flash>
+        </Box>
+      )}
       <TabGroup className="mt-6 flex-1 flex flex-col">
         <TabList>
           <Tab>Repositories</Tab>
+          <Tab>Documentation</Tab>
         </TabList>
         <TabPanels className="flex-1 flex flex-col">
           <TabPanel className="flex-1">
             <RepositoriesTable />
           </TabPanel>
+          <TabPanel className="flex-1">
+            <Box className="prose dark:prose-invert prose-lg">
+              <Documentation />
+            </Box>
+          </TabPanel>
         </TabPanels>
       </TabGroup>
     </main>

who-metrics-ui/src/hooks/useIsSSR.ts

@@ -0,0 +1,12 @@
+/* eslint-disable filenames/match-regex */
+import { useEffect, useState } from 'react';
+
+export const useIsSSR = () => {
+  const [isSSR, setIsSSR] = useState(true);
+
+  useEffect(() => {
+    setIsSSR(false);
+  }, []);
+
+  return isSSR;
+};

who-metrics-ui/src/types/markdown.d.ts

@@ -0,0 +1,5 @@
+// declared module for importing markdown files
+declare module '*.md' {
+  const value: string;
+  export default value;
+}

who-metrics-ui/tailwind.config.js

@@ -1,5 +1,6 @@
 /** @type {import('tailwindcss').Config} */
 
+
 module.exports = {
   darkMode: 'class',
   content: [
@@ -10,6 +11,34 @@ module.exports = {
     transparent: 'transparent',
     current: 'currentColor',
     extend: {
+      typography: (theme) => ({
+        DEFAULT: {
+          css: {
+            maxWidth: '2000px',
+            code: {
+              backgroundColor: theme('colors.tremor.background.muted'),
+              padding: '0.25rem 0.5rem',
+              borderRadius: theme('borderRadius.tremor-small')
+              // Now need to do that for dark mode
+            },
+            'code::before': {
+              content: '""',
+            },
+            'code::after': {
+              content: '""',
+            },
+          }
+        },
+        invert: {
+          css: {
+            code: {
+              backgroundColor: theme('colors.dark-tremor.background.muted'),
+              padding: '0.25rem 0.5rem',
+              borderRadius: theme('borderRadius.tremor-small')
+            },
+          }
+        }
+      }),
       height: {
         100: '24rem',
         120: '30rem',
@@ -148,5 +177,5 @@ module.exports = {
         /^(fill-(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(?:50|100|200|300|400|500|600|700|800|900|950))$/
     }
   ],
-  plugins: [require('@headlessui/tailwindcss')]
+  plugins: [require('@headlessui/tailwindcss'), require('@tailwindcss/typography'),]
 }