[learn-example][m] - add facets to catalog component

* [#812,package][xl]: package preparation, replace components on learn-example

* [#812,package][xs]: upgrade portaljs/components version on learn-example

* [package][xs]: add deboundebinput back to lean-example

examples/learn-example/components/Catalog.tsx

@@ -0,0 +1,119 @@
+import { Index } from 'flexsearch';
+import { useState } from 'react';
+import DebouncedInput from './DebouncedInput';
+import { useForm } from 'react-hook-form';
+
+export default function Catalog({
+  datasets,
+  facets,
+}: {
+  datasets: any[];
+  facets: string[];
+}) {
+  const [indexFilter, setIndexFilter] = useState('');
+  const index = new Index({ tokenize: 'full' });
+  datasets.forEach((dataset) =>
+    index.add(
+      dataset._id,
+      //This will join every metadata value + the url_path into one big string and index that
+      Object.entries(dataset.metadata).reduce(
+        (acc, curr) => acc + ' ' + curr[1].toString(),
+        ''
+      ) +
+        ' ' +
+        dataset.url_path
+    )
+  );
+
+  const facetValues = facets
+    ? facets.reduce((acc, facet) => {
+        const possibleValues = datasets.reduce((acc, curr) => {
+          const facetValue = curr.metadata[facet];
+          if (facetValue) {
+            return Array.isArray(facetValue)
+              ? acc.concat(facetValue)
+              : acc.concat([facetValue]);
+          }
+          return acc;
+        }, []);
+        acc[facet] = {
+          possibleValues: [...new Set(possibleValues)],
+          selectedValue: null,
+        };
+        return acc;
+      }, {})
+    : [];
+
+  const { register, watch } = useForm(facetValues);
+
+  const filteredDatasets = datasets
+    // First filter by flex search
+    .filter((dataset) =>
+      indexFilter !== ''
+        ? index.search(indexFilter).includes(dataset._id)
+        : true
+    )
+    //Then check if the selectedValue for the given facet is included in the dataset metadata
+    .filter((dataset) => {
+      //Avoids a server rendering breakage
+      if (!watch() || Object.keys(watch()).length === 0) return true
+      //This will filter only the key pairs of the metadata values that were selected as facets
+      const datasetFacets = Object.entries(dataset.metadata).filter((entry) =>
+        facets.includes(entry[0])
+      );
+      //Check if the value present is included in the selected value in the form
+      return datasetFacets.every((elem) =>
+        watch()[elem[0]].selectedValue
+          ? (elem[1] as string | string[]).includes(
+              watch()[elem[0]].selectedValue
+            )
+          : true
+      );
+    });
+
+  return (
+    <>
+      <DebouncedInput
+        value={indexFilter ?? ''}
+        onChange={(value) => setIndexFilter(String(value))}
+        className="p-2 text-sm shadow border border-block mr-1"
+        placeholder="Search all datasets..."
+      />
+      {Object.entries(facetValues).map((elem) => (
+        <select
+          key={elem[0]}
+          defaultValue=""
+          className="p-2 ml-1 text-sm shadow border border-block"
+          {...register(elem[0] + '.selectedValue')}
+        >
+          <option value="">
+            Filter by {elem[0]}
+          </option>
+          {(elem[1] as { possibleValues: string[] }).possibleValues.map(
+            (val) => (
+              <option
+                key={val}
+                className="dark:bg-white dark:text-black"
+                value={val}
+              >
+                {val}
+              </option>
+            )
+          )}
+        </select>
+      ))}
+      <ul>
+        {filteredDatasets.map((dataset) => (
+          <li key={dataset._id}>
+            <a href={dataset.url_path}>
+              {dataset.metadata.title
+                ? dataset.metadata.title
+                : dataset.url_path}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+}
+

examples/learn-example/components/DataRichDocument.tsx

@@ -7,13 +7,12 @@ import { Mermaid } from '@flowershow/core';
 // to handle import statements. Instead, you must include components in scope
 // here.
 const components = {
-  Table: dynamic(() => import('./Table')),
+  Table: dynamic(() => import('@portaljs/components').then(mod => mod.Table)),
+  Catalog: dynamic(() => import('./Catalog')),
   mermaid: Mermaid,
-  // Excel: dynamic(() => import('../components/Excel')),
-  // TODO: try and make these dynamic ...
-  Vega: dynamic(() => import('./Vega')),
-  VegaLite: dynamic(() => import('./VegaLite')),
-  LineChart: dynamic(() => import('./LineChart')),
+  Vega: dynamic(() => import('@portaljs/components').then(mod => mod.Vega)),
+  VegaLite: dynamic(() => import('@portaljs/components').then(mod => mod.VegaLite)),
+  LineChart: dynamic(() => import('@portaljs/components').then(mod => mod.LineChart)),
 } as any;
 
 export default function DRD({ source }: { source: any }) {

examples/learn-example/components/LineChart.tsx

@@ -1,55 +0,0 @@
-import VegaLite from "./VegaLite";
-
-export default function LineChart({
-  data = [],
-  fullWidth = false,
-  title = "",
-  xAxis = "x",
-  yAxis = "y",
-}) {
-  var tmp = data;
-  if (Array.isArray(data)) {
-    tmp = data.map((r, i) => {
-      return { x: r[0], y: r[1] };
-    });
-  }
-  const vegaData = { table: tmp };
-  const spec = {
-    $schema: "https://vega.github.io/schema/vega-lite/v5.json",
-    title,
-    width: "container",
-    height: 300,
-    mark: {
-      type: "line",
-      color: "black",
-      strokeWidth: 1,
-      tooltip: true,
-    },
-    data: {
-      name: "table",
-    },
-    selection: {
-      grid: {
-        type: "interval",
-        bind: "scales",
-      },
-    },
-    encoding: {
-      x: {
-        field: xAxis,
-        timeUnit: "year",
-        type: "temporal",
-      },
-      y: {
-        field: yAxis,
-        type: "quantitative",
-      },
-    },
-  };
-  if (typeof data === 'string') {
-    spec.data = { "url": data } as any
-    return <VegaLite fullWidth={fullWidth} spec={spec} />;
-  }
-
-  return <VegaLite fullWidth={fullWidth} data={vegaData} spec={spec} />;
-}

examples/learn-example/components/Table.tsx

@@ -1,189 +0,0 @@
-import {
-  createColumnHelper,
-  FilterFn,
-  flexRender,
-  getCoreRowModel,
-  getFilteredRowModel,
-  getPaginationRowModel,
-  getSortedRowModel,
-  useReactTable,
-} from "@tanstack/react-table";
-
-import {
-  ArrowDownIcon,
-  ArrowUpIcon,
-  ChevronDoubleLeftIcon,
-  ChevronDoubleRightIcon,
-  ChevronLeftIcon,
-  ChevronRightIcon,
-} from "@heroicons/react/24/solid";
-
-import React, { useEffect, useMemo, useState } from "react";
-
-import parseCsv from "../lib/parseCsv";
-import DebouncedInput from "./DebouncedInput";
-import loadData from "../lib/loadData";
-
-const Table = ({
-  data: ogData = [],
-  cols: ogCols = [],
-  csv = "",
-  url = "",
-  fullWidth = false,
-}) => {
-  if (csv) {
-    const out = parseCsv(csv);
-    ogData = out.rows;
-    ogCols = out.fields;
-  }
-
-  const [data, setData] = React.useState(ogData);
-  const [cols, setCols] = React.useState(ogCols);
-  const [error, setError] = React.useState(""); //  TODO: add error handling
-
-  const tableCols = useMemo(() => {
-    const columnHelper = createColumnHelper();
-    return cols.map((c) =>
-      columnHelper.accessor(c.key, {
-        header: () => c.name,
-        cell: (info) => info.getValue(),
-      })
-    );
-  }, [data, cols]);
-
-  const [globalFilter, setGlobalFilter] = useState("");
-
-  const table = useReactTable({
-    data,
-    columns: tableCols,
-    getCoreRowModel: getCoreRowModel(),
-    state: {
-      globalFilter,
-    },
-    globalFilterFn: globalFilterFn,
-    onGlobalFilterChange: setGlobalFilter,
-    getFilteredRowModel: getFilteredRowModel(),
-    getPaginationRowModel: getPaginationRowModel(),
-    getSortedRowModel: getSortedRowModel(),
-  });
-
-  useEffect(() => {
-    if (url) {
-      loadData(url).then((data) => {
-        const { rows, fields } = parseCsv(data);
-        setData(rows);
-        setCols(fields);
-      });
-    }
-  }, [url]);
-
-  return (
-    <div className={`${fullWidth ? "w-[90vw] ml-[calc(50%-45vw)]" : "w-full"}`}>
-      <DebouncedInput
-        value={globalFilter ?? ""}
-        onChange={(value) => setGlobalFilter(String(value))}
-        className="p-2 text-sm shadow border border-block"
-        placeholder="Search all columns..."
-      />
-      <table>
-        <thead>
-          {table.getHeaderGroups().map((hg) => (
-            <tr key={hg.id}>
-              {hg.headers.map((h) => (
-                <th key={h.id}>
-                  <div
-                    {...{
-                      className: h.column.getCanSort()
-                        ? "cursor-pointer select-none"
-                        : "",
-                      onClick: h.column.getToggleSortingHandler(),
-                    }}
-                  >
-                    {flexRender(h.column.columnDef.header, h.getContext())}
-                    {{
-                      asc: (
-                        <ArrowUpIcon className="inline-block ml-2 h-4 w-4" />
-                      ),
-                      desc: (
-                        <ArrowDownIcon className="inline-block ml-2 h-4 w-4" />
-                      ),
-                    }[h.column.getIsSorted() as string] ?? (
-                      <div className="inline-block ml-2 h-4 w-4" />
-                    )}
-                  </div>
-                </th>
-              ))}
-            </tr>
-          ))}
-        </thead>
-        <tbody>
-          {table.getRowModel().rows.map((r) => (
-            <tr key={r.id}>
-              {r.getVisibleCells().map((c) => (
-                <td key={c.id}>
-                  {flexRender(c.column.columnDef.cell, c.getContext())}
-                </td>
-              ))}
-            </tr>
-          ))}
-        </tbody>
-      </table>
-      <div className="flex gap-2 items-center justify-center">
-        <button
-          className={`w-6 h-6 ${
-            !table.getCanPreviousPage() ? "opacity-25" : "opacity-100"
-          }`}
-          onClick={() => table.setPageIndex(0)}
-          disabled={!table.getCanPreviousPage()}
-        >
-          <ChevronDoubleLeftIcon />
-        </button>
-        <button
-          className={`w-6 h-6 ${
-            !table.getCanPreviousPage() ? "opacity-25" : "opacity-100"
-          }`}
-          onClick={() => table.previousPage()}
-          disabled={!table.getCanPreviousPage()}
-        >
-          <ChevronLeftIcon />
-        </button>
-        <span className="flex items-center gap-1">
-          <div>Page</div>
-          <strong>
-            {table.getState().pagination.pageIndex + 1} of{" "}
-            {table.getPageCount()}
-          </strong>
-        </span>
-        <button
-          className={`w-6 h-6 ${
-            !table.getCanNextPage() ? "opacity-25" : "opacity-100"
-          }`}
-          onClick={() => table.nextPage()}
-          disabled={!table.getCanNextPage()}
-        >
-          <ChevronRightIcon />
-        </button>
-        <button
-          className={`w-6 h-6 ${
-            !table.getCanNextPage() ? "opacity-25" : "opacity-100"
-          }`}
-          onClick={() => table.setPageIndex(table.getPageCount() - 1)}
-          disabled={!table.getCanNextPage()}
-        >
-          <ChevronDoubleRightIcon />
-        </button>
-      </div>
-    </div>
-  );
-};
-
-const globalFilterFn: FilterFn<any> = (row, columnId, filterValue: string) => {
-  const search = filterValue.toLowerCase();
-
-  let value = row.getValue(columnId) as string;
-  if (typeof value === "number") value = String(value);
-
-  return value?.toLowerCase().includes(search);
-};
-
-export default Table;

examples/learn-example/components/Vega.tsx

@@ -1,6 +0,0 @@
-//  Wrapper for the Vega component
-import { Vega as VegaOg } from "react-vega";
-
-export default function Vega(props) {
-  return <VegaOg {...props} />;
-}

examples/learn-example/components/VegaLite.tsx

@@ -1,9 +0,0 @@
-//  Wrapper for the Vega Lite component
-import { VegaLite as VegaLiteOg } from "react-vega";
-import applyFullWidthDirective from "../lib/applyFullWidthDirective";
-
-export default function VegaLite(props) {
-  const Component = applyFullWidthDirective({ Component: VegaLiteOg });
-
-  return <Component {...props} />;
-}

examples/learn-example/lib/applyFullWidthDirective.tsx

@@ -1,21 +0,0 @@
-export default function applyFullWidthDirective({
-  Component,
-  defaultWFull = true,
-}) {
-  return (props) => {
-    const newProps = { ...props };
-
-    let newClassName = newProps.className || "";
-    if (newProps.fullWidth === true) {
-      newClassName += " w-[90vw] ml-[calc(50%-45vw)] max-w-none";
-    } else if (defaultWFull) {
-      //  So that charts and tables will have the
-      //  same width as the text content, but images
-      //  can have its width set using the width prop
-      newClassName += " w-full";
-    }
-    newProps.className = newClassName;
-
-    return <Component {...newProps} />;
-  };
-}

examples/learn-example/lib/loadData.tsx

@@ -1,5 +0,0 @@
-export default async function loadData(url: string) {
-  const response = await fetch(url)
-  const data = await response.text()
-  return data
-}

examples/learn-example/lib/markdown.js

@@ -22,7 +22,7 @@ import { serialize } from "next-mdx-remote/serialize";
  * @format: used to indicate to next-mdx-remote which format to use (md or mdx)
  * @returns: { mdxSource: mdxSource, frontMatter: ...}
  */
-const parse = async function (source, format) {
+const parse = async function (source, format, scope) {
   const { content, data, excerpt } = matter(source, {
     excerpt: (file, options) => {
       // Generate an excerpt for the file
@@ -91,7 +91,7 @@ const parse = async function (source, format) {
         ],
         format,
       },
-      scope: data,
+      scope,
     }
   );
 

examples/learn-example/lib/mddb.ts

@@ -0,0 +1,14 @@
+import { MarkdownDB } from "@flowershow/markdowndb";
+
+const dbPath = "markdown.db";
+
+const client = new MarkdownDB({
+  client: "sqlite3",
+  connection: {
+    filename: dbPath,
+  },
+});
+
+const clientPromise = client.init();
+
+export default clientPromise;

examples/learn-example/lib/parseCsv.ts

@@ -1,16 +0,0 @@
-import papa from "papaparse";
-
-const parseCsv = (csv) => {
-  csv = csv.trim();
-  const rawdata = papa.parse(csv, { header: true });
-  const cols = rawdata.meta.fields.map((r, i) => {
-    return { key: r, name: r };
-  });
-
-  return {
-    rows: rawdata.data,
-    fields: cols,
-  };
-};
-
-export default parseCsv;

examples/learn-example/package.json

@@ -7,21 +7,26 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "export": "npm run build && next export -o out"
+    "export": "npm run build && next export -o out",
+    "prebuild": "npm run mddb",
+    "mddb": "mddb ./content"
   },
   "dependencies": {
     "@flowershow/core": "^0.4.10",
+    "@flowershow/markdowndb": "^0.1.1",
     "@flowershow/remark-callouts": "^1.0.0",
     "@flowershow/remark-embed": "^1.0.0",
     "@flowershow/remark-wiki-link": "^1.1.2",
     "@heroicons/react": "^2.0.17",
     "@opentelemetry/api": "^1.4.0",
+    "@portaljs/components": "^0.0.3",
     "@tanstack/react-table": "^8.8.5",
     "@types/node": "18.16.0",
     "@types/react": "18.2.0",
     "@types/react-dom": "18.2.0",
     "eslint": "8.39.0",
     "eslint-config-next": "13.3.1",
+    "flexsearch": "0.7.21",
     "gray-matter": "^4.0.3",
     "hastscript": "^7.2.0",
     "mdx-mermaid": "2.0.0-rc7",
@@ -30,6 +35,7 @@
     "papaparse": "^5.4.1",
     "react": "18.2.0",
     "react-dom": "18.2.0",
+    "react-hook-form": "^7.43.9",
     "react-vega": "^7.6.0",
     "rehype-autolink-headings": "^6.1.1",
     "rehype-katex": "^6.0.3",
@@ -43,6 +49,7 @@
   },
   "devDependencies": {
     "@tailwindcss/typography": "^0.5.9",
+    "@types/flexsearch": "^0.7.3",
     "autoprefixer": "^10.4.14",
     "postcss": "^8.4.23",
     "tailwindcss": "^3.3.1"

examples/learn-example/pages/[[...path]].tsx

@@ -1,7 +1,9 @@
-import { promises as fs } from 'fs';
+import { existsSync, promises as fs } from 'fs';
 import path from 'path';
 import parse from '../lib/markdown';
-import DRD from '../components/DRD';
+
+import DataRichDocument from '../components/DataRichDocument';
+import clientPromise from '../lib/mddb';
 
 export const getStaticPaths = async () => {
   const contentDir = path.join(process.cwd(), '/content/');
@@ -23,9 +25,28 @@ export const getStaticProps = async (context) => {
     pathToFile = context.params.path.join('/') + '/index.md';
   }
 
+  let datasets = [];
+  const mddbFileExists = existsSync('markdown.db');
+  if (mddbFileExists) {
+    const mddb = await clientPromise;
+    const datasetsFiles = await mddb.getFiles({
+      extensions: ['md', 'mdx'],
+    });
+    datasets = datasetsFiles
+      .filter((dataset) => dataset.url_path !== '/')
+      .map((dataset) => ({
+        _id: dataset._id,
+        url_path: dataset.url_path,
+        file_path: dataset.file_path,
+        metadata: dataset.metadata,
+      }));
+  }
+
   const indexFile = path.join(process.cwd(), '/content/' + pathToFile);
   const readme = await fs.readFile(indexFile, 'utf8');
-  let { mdxSource, frontMatter } = await parse(readme, '.mdx');
+
+  let { mdxSource, frontMatter } = await parse(readme, '.mdx', { datasets });
+
   return {
     props: {
       mdxSource,
@@ -53,7 +74,7 @@ export default function DatasetPage({ mdxSource, frontMatter }) {
         </div>
       </header>
       <main>
-        <DRD source={mdxSource} />
+        <DataRichDocument source={mdxSource} />
       </main>
     </div>
   );

examples/learn-example/pages/_app.tsx

@@ -1,4 +1,6 @@
 import '../styles/globals.css'
+import '@portaljs/components/styles.css'
+
 import type { AppProps } from 'next/app'
 
 export default function App({ Component, pageProps }: AppProps) {

examples/learn-example/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "target": "es5",
+    "target": "es6",
     "lib": ["dom", "dom.iterable", "esnext"],
     "allowJs": true,
     "skipLibCheck": true,

packages/components/README.md

@@ -1,32 +1,29 @@
-# `components` package
+# PortalJS React Components
 
-**See live:** https://storybook.portaljs.org
+**Storybook:** https://storybook.portaljs.org  
+**Docs**: https://portaljs.org/docs  
+
+## Usage
+
+To install this package on your project:
+
+```bash
+npm i @portaljs/components
+```
+
+> Note: React 18 is required.
+
+You'll also have to import the styles CSS file in your project:
+
+```ts
+//  E.g.: Next.js => pages/_app.tsx
+import '@portaljs/components/styles.css'
+```
 
 ## Dev
 
 Use Storybook to work on components by running:
 
 ```bash
-yarn storybook
+npm run storybook
 ```
-
-## Build
-
-To build this project, run:
-
-```bash
-yarn build
-```
-
-## Install
-
-TODO: command to install the package
-
-### Next.js
-
-Add this line at the start of `_app.tsx`:
-
-```ts
-//  pages/_app.tsx
-import "dist/styles.css";
-```

packages/components/package.json

@@ -1,11 +1,18 @@
 {
-  "name": "components",
-  "private": true,
-  "version": "0.0.1",
+  "name": "@portaljs/components",
+  "version": "0.0.3",
   "type": "module",
+  "description": "https://portaljs.org",
+  "keywords": [
+    "data portal",
+    "data catalog",
+    "table",
+    "charts",
+    "visualization"
+  ],
   "scripts": {
-    "dev": "yarn storybook",
-    "build": "tsc && vite build && yarn build-tailwind",
+    "dev": "npm run storybook",
+    "build": "tsc && vite build && npm run build-tailwind",
     "lint": "eslint src --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "prepack": "json -f package.json -I -e \"delete this.devDependencies; delete this.dependencies\"",
     "storybook": "storybook dev -p 6006",
@@ -65,6 +72,12 @@
     ".": {
       "import": "./dist/components.es.js",
       "require": "./dist/components.umd.js"
+    },
+    "./styles.css": {
+      "import": "./dist/styles.css"
     }
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

site/content/docs/index.md

@@ -116,6 +116,52 @@ From the browser, access http://localhost:3000. You should see the following:
 
 <img src="/assets/docs/datasets-index-page.png" />
 
+### Creating a search page
+
+Typing out every link in the index page will get cumbersome eventually, and as the portal grows, finding the datasets you are looking for on the index page will become harder and harder. Luckily we have a component for that. Change your `content/index.md` file to this:
+
+```
+# Welcome to my data portal!
+
+List of available datasets:
+
+<Catalog datasets={datasets} />
+```
+
+Before you refresh the page, however, you will need to run the following command:
+
+```
+npm run mddb
+```
+
+This example makes use of the [markdowndb](https://github.com/datopian/markdowndb) library. For now the only thing you need to know is that you should run the command above everytime you make some change to `/content`.
+
+From the browser, access http://localhost:3000. You should see the following, you now have a searchable automatic list of your datasets:
+
+![](https://i.imgur.com/9HfSPIx.png)
+
+To make this catalog look even better, we can change the text that is being displayed for each dataset to a title. Let's do that by adding the "title" [frontmatter field](https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/) to the first dataset in the list. Change `content/my-awesome-dataset/index.md` to the following:
+
+```
+---
+title: 'My awesome dataset'
+---
+
+# My Awesome Dataset
+
+Built with PortalJS 
+
+## Table 
+
+<Table url="data.csv" />
+```
+
+Rerun `npm run mddb` and, from the browser, access http://localhost:3000. You should see the title appearing instead of the folder name:
+
+![](https://i.imgur.com/nvmSnJ5.png)
+
+Any frontmatter attribute that you add will automatically get indexed and be usable in the search box.
+
 ## Deploying your PortalJS app
 
 Finally, let's learn how to deploy PortalJS apps to Vercel or Cloudflare Pages.