@databiosphere/findable-ui 29.0.2 → 31.0.0

package/lib/views/ExploreView/exploreView.js

@@ -46,9 +46,10 @@ export const ExploreView = (props) => {
      * @param selectedCategoryValue - The value to set or clear.
      * @param selected - Indication of whether the selected value is being set or cleared.
      * @param categorySection - Name of group the category is in.
+     * @param viewKind - View kind.
      * @param searchTerm - Search term used to find the value.
      */
-    const onFilterChange = (fromSearchAll, categoryKey, selectedCategoryValue, selected, categorySection, searchTerm) => {
+    const onFilterChange = (fromSearchAll, categoryKey, selectedCategoryValue, selected, categorySection, viewKind, searchTerm) => {
         const dispatchType = categoryKey === SELECT_CATEGORY_KEY.SAVED_FILTERS
             ? ExploreActionKind.ApplySavedFilter
             : ExploreActionKind.UpdateFilter;
@@ -57,6 +58,7 @@ export const ExploreView = (props) => {
                 categoryKey,
                 selected,
                 selectedValue: selectedCategoryValue,
+                viewKind,
             },
             type: dispatchType,
         });
@@ -107,25 +109,25 @@ export const ExploreView = (props) => {
 };
 /**
  * Builds the category views into category views grouped by the given category group configuration.
- * @param selectCategoryViews - View models of categories to display.
+ * @param categoryViews - View models of categories to display.
  * @param categoryGroups - Category groups.
  * @returns category filters.
  */
-function buildCategoryFilters(selectCategoryViews, categoryGroups) {
+function buildCategoryFilters(categoryViews, categoryGroups) {
     if (!categoryGroups) {
-        return [{ categoryViews: selectCategoryViews }];
+        return [{ categoryViews }];
     }
     return categoryGroups.reduce((accGroups, { categoryConfigs, label }) => {
         // Grab the category views for the configured grouped categories.
-        const categoryViews = categoryConfigs.reduce((accViews, { key: categoryKey }) => {
-            const categoryView = selectCategoryViews.find(({ key }) => key === categoryKey);
+        const views = categoryConfigs.reduce((accViews, { key: categoryKey }) => {
+            const categoryView = categoryViews.find(({ key }) => key === categoryKey);
             if (categoryView) {
                 accViews.push(categoryView);
             }
             return accViews;
         }, []);
-        if (categoryViews.length > 0) {
-            accGroups.push({ categoryViews, label });
+        if (views.length > 0) {
+            accGroups.push({ categoryViews: views, label });
         }
         return accGroups;
     }, []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databiosphere/findable-ui",
-  "version": "29.0.2",
+  "version": "31.0.0",
   "description": "",
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
@@ -24,6 +24,7 @@
   "devDependencies": {
     "@commitlint/cli": "^17.4.2",
     "@commitlint/config-conventional": "^17.4.2",
+    "@emotion/jest": "^11.13.0",
     "@mui/types": "^7.4.0",
     "@next/eslint-plugin-next": "^14.2.28",
     "@storybook/addon-actions": "^8.6.4",
@@ -61,6 +62,11 @@
     "jest-fetch-mock": "^3.0.3",
     "prettier": "^2.8.3",
     "prettier-plugin-organize-imports": "^3.2.2",
+    "rehype-raw": "^7.0.0",
+    "rehype-react": "^8.0.0",
+    "rehype-sanitize": "^6.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-rehype": "^11.1.2",
     "storybook": "^8.6.4",
     "ts-jest": "^29.2.5",
     "typescript": "^5.5.4"

package/src/common/categories/config/types.ts

@@ -0,0 +1,42 @@
+import {
+  CategoryKey,
+  DataDictionaryAnnotation,
+  SelectCategoryValueView,
+} from "../../entities";
+import { RangeViewKind } from "../views/range/types";
+import { SelectViewKind } from "../views/select/types";
+
+/**
+ * Category config.
+ */
+export type CategoryConfig = RangeCategoryConfig | SelectCategoryConfig;
+
+/**
+ * Common category config.
+ */
+export interface CommonCategoryConfig {
+  annotation?: DataDictionaryAnnotation;
+  key: CategoryKey;
+  label: string; // human readable label
+}
+
+/**
+ * Range category config.
+ */
+export interface RangeCategoryConfig
+  extends CommonCategoryConfig,
+    RangeViewKind {
+  unit?: string; // e.g. "kg"
+}
+
+/**
+ * Select category config.
+ */
+export interface SelectCategoryConfig
+  extends CommonCategoryConfig,
+    SelectViewKind {
+  enableChartView?: boolean;
+  mapSelectCategoryValue?: (
+    selectCategoryValue: SelectCategoryValueView
+  ) => SelectCategoryValueView;
+}

package/src/common/categories/config/utils.ts

@@ -0,0 +1,47 @@
+import { Category } from "../models/types";
+import { VIEW_KIND } from "../views/types";
+import { CategoryConfig } from "./types";
+
+/**
+ * Returns the category config for the given category config key and view kind.
+ * @param viewKind - View kind.
+ * @param key - Category config key.
+ * @param configs - Category configs.
+ * @returns category config.
+ */
+export function findCategoryConfig<V extends VIEW_KIND>(
+  viewKind: V,
+  key: Category["key"],
+  configs: CategoryConfig[]
+): Extract<CategoryConfig, { viewKind: V }> | undefined {
+  return configs.find(
+    (c): c is Extract<CategoryConfig, { viewKind: V }> =>
+      c.viewKind === viewKind && c.key === key
+  );
+}
+
+/**
+ * Returns the range category config for the given category config key.
+ * @param key - Category config key.
+ * @param configs - Category configs.
+ * @returns category config.
+ */
+export function findRangeCategoryConfig(
+  key: Category["key"],
+  configs: CategoryConfig[]
+): Extract<CategoryConfig, { viewKind: VIEW_KIND.RANGE }> | undefined {
+  return findCategoryConfig(VIEW_KIND.RANGE, key, configs);
+}
+
+/**
+ * Returns the select category config for the given category config key.
+ * @param key - Category config key.
+ * @param configs - Category configs.
+ * @returns category config.
+ */
+export function findSelectCategoryConfig(
+  key: Category["key"],
+  configs: CategoryConfig[]
+): Extract<CategoryConfig, { viewKind?: VIEW_KIND.SELECT }> | undefined {
+  return findCategoryConfig(VIEW_KIND.SELECT, key, configs);
+}

package/src/common/categories/models/range/typeGuards.ts

@@ -0,0 +1,24 @@
+import { Category } from "../types";
+import { RangeCategory, SelectedRange } from "./types";
+
+/**
+ * Determine if category is a range category.
+ * @param category - Category to check if range category.
+ * @returns true if category is a range category.
+ */
+export function isRangeCategory(category: Category): category is RangeCategory {
+  return "max" in category && "min" in category;
+}
+
+/**
+ * Determine if value is a selected range.
+ * @param value - Value to check if selected range.
+ * @returns true if value is a selected range.
+ */
+export function isSelectedRange(value: unknown): value is SelectedRange {
+  return (
+    Array.isArray(value) &&
+    value.length === 2 &&
+    value.every((v) => v === null || typeof v === "number")
+  );
+}

package/src/common/categories/models/range/types.ts

@@ -0,0 +1,17 @@
+import { CategoryKey } from "../../../entities";
+
+/**
+ * Internal filter model of a range category.
+ */
+export interface RangeCategory {
+  key: CategoryKey;
+  max: number;
+  min: number;
+  selectedMax: SelectedRange[1];
+  selectedMin: SelectedRange[0];
+}
+
+/**
+ * Min and max values selected in range category.
+ */
+export type SelectedRange = [number | null, number | null];

package/src/common/categories/models/range/utils.ts

@@ -0,0 +1,51 @@
+import { CategoryValueKey, SelectedFilter } from "../../../entities";
+import { isSelectedRange } from "./typeGuards";
+import { SelectedRange } from "./types";
+
+/**
+ * Asserts that the given value is a selected range.
+ * Throws an error if the value is not a selected range.
+ * @param value - Value to assert is a selected range.
+ */
+export function assertIsRange(value: unknown): asserts value is SelectedRange {
+  if (!isSelectedRange(value)) {
+    throw new Error("Value is not SelectedRange");
+  }
+}
+
+/**
+ * Build the next filter state for the given range category.
+ * @param nextCategorySelectedFilter - Next filter state for the range category.
+ * @param selectedValue - Selected value for the range category.
+ * @param selected - Whether the category value is selected.
+ */
+export function buildNextRangeFilterState(
+  nextCategorySelectedFilter: SelectedFilter,
+  selectedValue: CategoryValueKey,
+  selected: boolean
+): void {
+  if (selected) {
+    // Assert that the selected value is a range.
+    assertIsRange(selectedValue);
+    // Set the selected range.
+    nextCategorySelectedFilter.value = selectedValue;
+  } else {
+    // Remove the selected range.
+    nextCategorySelectedFilter.value = [];
+  }
+}
+
+/**
+ * Get the selected values for the given category, if any.
+ * Handles type checking for selected range.
+ * Falls back to empty array if no selected values or invalid type (should never happen).
+ * @param categorySelectedFilter - Current filter state for a category.
+ * @returns The selected filter (i.e. the set of selected values) for the given category.
+ */
+export function getRangeSelectedValue(
+  categorySelectedFilter?: SelectedFilter
+): SelectedRange {
+  return isSelectedRange(categorySelectedFilter?.value)
+    ? categorySelectedFilter?.value
+    : [null, null];
+}

package/src/common/categories/models/select/utils.ts

@@ -0,0 +1,23 @@
+import { CategoryValueKey, SelectedFilter } from "../../../entities";
+
+/**
+ * Build the next filter state for the given select category.
+ * @param nextCategorySelectedFilter - Next filter state for the select category.
+ * @param selectedValue - Selected value for the select category.
+ * @param selected - Whether the category value is selected.
+ */
+export function buildNextSelectFilterState(
+  nextCategorySelectedFilter: SelectedFilter,
+  selectedValue: CategoryValueKey,
+  selected: boolean
+): void {
+  if (selected) {
+    // Set the selected value.
+    nextCategorySelectedFilter.value.push(selectedValue);
+  } else {
+    // Remove the selected value from the selected set of values.
+    nextCategorySelectedFilter.value = nextCategorySelectedFilter.value.filter(
+      (value: CategoryValueKey) => value !== selectedValue
+    );
+  }
+}

package/src/common/categories/models/types.ts

@@ -0,0 +1,7 @@
+import { SelectCategory } from "../../entities";
+import { RangeCategory } from "./range/types";
+
+/**
+ * Internal filter model of a category.
+ */
+export type Category = SelectCategory | RangeCategory;

package/src/common/categories/views/common/types.ts

@@ -0,0 +1,11 @@
+import { CategoryKey, DataDictionaryAnnotation } from "../../../entities";
+
+/**
+ * Common properties for category views.
+ */
+export interface BaseCategoryView {
+  annotation?: DataDictionaryAnnotation;
+  isDisabled?: boolean;
+  key: CategoryKey;
+  label: string;
+}

package/src/common/categories/views/range/typeGuards.ts

@@ -0,0 +1,13 @@
+import { CategoryView } from "../types";
+import { RangeCategoryView } from "./types";
+
+/**
+ * Returns true if the category view is a range category view.
+ * @param view - Category view.
+ * @returns true if the category view is a range category view.
+ */
+export function isRangeCategoryView(
+  view: CategoryView
+): view is RangeCategoryView {
+  return "max" in view && "min" in view;
+}

package/src/common/categories/views/range/types.ts

@@ -0,0 +1,21 @@
+import { SelectedRange } from "../../models/range/types";
+import { BaseCategoryView } from "../common/types";
+import { VIEW_KIND } from "../types";
+
+/**
+ * View model of range category.
+ */
+export interface RangeCategoryView extends BaseCategoryView {
+  max: number;
+  min: number;
+  selectedMax: SelectedRange[1];
+  selectedMin: SelectedRange[0];
+  unit?: string;
+}
+
+/**
+ * Model of range category view kind.
+ */
+export interface RangeViewKind {
+  viewKind: VIEW_KIND.RANGE;
+}

package/src/common/categories/views/range/utils.ts

@@ -0,0 +1,35 @@
+import { SelectedFilter } from "../../../entities";
+import { CategoryConfig } from "../../config/types";
+import { findRangeCategoryConfig } from "../../config/utils";
+import { RangeCategory } from "../../models/range/types";
+import { getRangeSelectedValue } from "../../models/range/utils";
+import { RangeCategoryView } from "../../views/range/types";
+
+/**
+ * Build the view-specific model of the given range category.
+ * @param category - The range category to build a view model of.
+ * @param categoryConfigs - Category configs indicating accept list as well as label configuration.
+ * @param categorySelectedFilter - Current filter state for a category.
+ * @returns Full built range category view, ready for display.
+ */
+export function buildRangeCategoryView(
+  category: RangeCategory,
+  categoryConfigs: CategoryConfig[],
+  categorySelectedFilter?: SelectedFilter
+): RangeCategoryView {
+  const categoryConfig = findRangeCategoryConfig(category.key, categoryConfigs);
+  const [selectedMin, selectedMax] = getRangeSelectedValue(
+    categorySelectedFilter
+  );
+  return {
+    annotation: categoryConfig?.annotation,
+    isDisabled: false,
+    key: category.key,
+    label: categoryConfig?.label || category.key,
+    max: category.max,
+    min: category.min,
+    selectedMax,
+    selectedMin,
+    unit: categoryConfig?.unit,
+  };
+}

package/src/common/categories/views/select/typeGuards.ts

@@ -0,0 +1,13 @@
+import { SelectCategoryView } from "../../../entities";
+import { CategoryView } from "../types";
+
+/**
+ * Returns true if the category view is a select category view.
+ * @param view - Category view.
+ * @returns true if the category view is a select category view.
+ */
+export function isSelectCategoryView(
+  view: CategoryView
+): view is SelectCategoryView {
+  return "values" in view;
+}

package/src/common/categories/views/select/types.ts

@@ -0,0 +1,8 @@
+import { VIEW_KIND } from "../types";
+
+/**
+ * Model of select category view kind.
+ */
+export interface SelectViewKind {
+  viewKind?: VIEW_KIND.SELECT;
+}

package/src/common/categories/views/types.ts

@@ -0,0 +1,15 @@
+import { SelectCategoryView } from "../../entities";
+import { RangeCategoryView } from "./range/types";
+
+/**
+ * Possible category view model types.
+ */
+export type CategoryView = RangeCategoryView | SelectCategoryView;
+
+/**
+ * Category view kind.
+ */
+export enum VIEW_KIND {
+  RANGE = "RANGE",
+  SELECT = "SELECT",
+}

package/src/common/entities.ts

@@ -1,4 +1,4 @@
-import { ColumnDef } from "@tanstack/react-table";
+import { ColumnDef, RowData } from "@tanstack/react-table";
 
 /**
  * Model of a value of a metadata class.
@@ -18,11 +18,6 @@ export interface Attribute {
   values?: string; // Free text description of attribute values
 }
 
-/**
- * Model of attribute key types; used mostly when building data dictionary column definitions.
- */
-export type AttributeValueTypes = string | boolean;
-
 /**
  * Filterable metadata keys.
  */
@@ -40,8 +35,8 @@ export interface CategoryTag {
 /**
  * Model of a metadata class, to be specified manually or built from LinkML schema.
  */
-export interface Class {
-  attributes: Attribute[];
+export interface Class<T extends RowData = Attribute> {
+  attributes: T[];
   description: string;
   name: string; // Programmatic name or key (e.g. cell, sample)
   title: string; // Display name
@@ -61,37 +56,24 @@ export type DataDictionaryPrefix = Record<string, string>;
 /**
  * Model of a metadata dictionary containing a set of classes and their definitions.
  */
-export interface DataDictionary {
+export interface DataDictionary<T extends RowData = Attribute> {
   annotations?: {
     [key in keyof DataDictionaryPrefix]: string; // Prefix to title e.g. "cxg": "CELLxGENE"
   };
-  classes: Class[];
+  classes: Class<T>[];
   description?: string; // Free text description of data dictionary
   name: string; // Programmatic name or key (e.g. tier1, hca)
   prefixes?: DataDictionaryPrefix;
   title: string; // Display name
 }
 
-/**
- * Display model of a data dictionary column.
- */
-export interface DataDictionaryColumnDef {
-  attributeDisplayName: string;
-  attributeSlotName: string;
-  // Adding width here for now; possibly revisit separating column def and UI.
-  width: {
-    max: string;
-    min: string;
-  };
-}
-
 /**
  * Configuration of data dictionary; contains schema definition (that is, the actual data
  * dictionary) as well as column def for displaying the data dictionary.
  */
-export interface DataDictionaryConfig {
-  columnDefs: ColumnDef<Attribute, AttributeValueTypes>[];
-  dataDictionary: DataDictionary;
+export interface DataDictionaryConfig<T extends RowData = Attribute> {
+  columnDefs: ColumnDef<T, T[keyof T]>[];
+  dataDictionary: DataDictionary<T>;
 }
 
 /**

package/src/components/DataDictionary/components/Entities/entities.tsx

@@ -1,20 +1,22 @@
 import { Grid } from "@mui/material";
+import { RowData } from "@tanstack/react-table";
 import React from "react";
+import { Attribute } from "../../../../common/entities";
 import { Entity } from "../Entity/entity";
 import { GRID_PROPS } from "./constants";
 import { ClassesProps } from "./types";
 
-export const Entities = ({
+export const Entities = <T extends RowData = Attribute>({
   classes,
   columnDefs,
   spacing,
-}: ClassesProps): JSX.Element => {
+}: ClassesProps<T>): JSX.Element => {
   return (
     <Grid {...GRID_PROPS}>
-      {classes.map((classData) => (
+      {classes.map((cls) => (
         <Entity
-          key={classData.name}
-          class={classData}
+          key={cls.name}
+          class={cls}
           columnDefs={columnDefs}
           spacing={spacing}
         />

package/src/components/DataDictionary/components/Entities/types.ts

@@ -1,13 +1,9 @@
-import { ColumnDef } from "@tanstack/react-table";
-import {
-  Attribute,
-  AttributeValueTypes,
-  Class,
-} from "../../../../common/entities";
+import { ColumnDef, RowData } from "@tanstack/react-table";
+import { Attribute, Class } from "../../../../common/entities";
 import { LayoutSpacing } from "../../hooks/UseLayoutSpacing/types";
 
-export interface ClassesProps {
-  classes: Class[];
-  columnDefs: ColumnDef<Attribute, AttributeValueTypes>[];
+export interface ClassesProps<T extends RowData = Attribute> {
+  classes: Class<T>[];
+  columnDefs: ColumnDef<T, T[keyof T]>[];
   spacing?: LayoutSpacing;
 }

package/src/components/DataDictionary/components/Entity/entity.tsx

@@ -1,5 +1,7 @@
 import { Grid, Typography } from "@mui/material";
+import { RowData } from "@tanstack/react-table";
 import React from "react";
+import { Attribute } from "../../../../common/entities";
 import { TYPOGRAPHY_PROPS } from "../../../../styles/common/mui/typography";
 import { AnchorLink } from "../../../common/AnchorLink/anchorLink";
 import { useTable } from "../Table/hook";
@@ -8,29 +10,29 @@ import { GRID_PROPS } from "./constants";
 import { StyledTypography } from "./entity.styles";
 import { EntityProps } from "./types";
 
-export const Entity = ({
-  class: classData,
+export const Entity = <T extends RowData = Attribute>({
+  class: cls,
   columnDefs,
   spacing,
-}: EntityProps): JSX.Element => {
-  const table = useTable(classData.attributes, columnDefs);
+}: EntityProps<T>): JSX.Element => {
+  const table = useTable<T>(cls.attributes, columnDefs);
   return (
     <Grid {...GRID_PROPS} rowGap={4}>
       <Grid {...GRID_PROPS} rowGap={1}>
         <StyledTypography
           component="h3"
-          id={classData.name}
+          id={cls.name}
           variant={TYPOGRAPHY_PROPS.VARIANT.TEXT_HEADING_SMALL}
           {...spacing}
         >
-          {classData.title} <AnchorLink anchorLink={classData.name} />
+          {cls.title} <AnchorLink anchorLink={cls.name} />
         </StyledTypography>
         <Typography
           color={TYPOGRAPHY_PROPS.COLOR.INK_LIGHT}
           component="div"
           variant={TYPOGRAPHY_PROPS.VARIANT.TEXT_BODY_400_2_LINES}
         >
-          {classData.description}
+          {cls.description}
         </Typography>
       </Grid>
       <Table table={table} />

package/src/components/DataDictionary/components/Entity/types.ts

@@ -1,13 +1,9 @@
-import { ColumnDef } from "@tanstack/react-table";
-import {
-  Attribute,
-  AttributeValueTypes,
-  Class,
-} from "../../../../common/entities";
+import { ColumnDef, RowData } from "@tanstack/react-table";
+import { Attribute, Class } from "../../../../common/entities";
 import { LayoutSpacing } from "../../hooks/UseLayoutSpacing/types";
 
-export interface EntityProps {
-  class: Class;
-  columnDefs: ColumnDef<Attribute, AttributeValueTypes>[];
+export interface EntityProps<T extends RowData = Attribute> {
+  class: Class<T>;
+  columnDefs: ColumnDef<T, T[keyof T]>[];
   spacing?: LayoutSpacing;
 }

package/src/components/DataDictionary/components/Outline/utils.ts

@@ -1,4 +1,5 @@
-import { Class } from "../../../../common/entities";
+import { RowData } from "@tanstack/react-table";
+import { Attribute, Class } from "../../../../common/entities";
 import { OutlineItem } from "../../../Layout/components/Outline/types";
 
 /**
@@ -6,7 +7,9 @@ import { OutlineItem } from "../../../Layout/components/Outline/types";
  * @param classes - Class entities.
  * @returns Outline items.
  */
-export function buildClassesOutline(classes: Class[]): OutlineItem[] {
+export function buildClassesOutline<T extends RowData = Attribute>(
+  classes: Class<T>[]
+): OutlineItem[] {
   return classes.map(({ name, title }) => {
     return {
       depth: 2,

package/src/components/DataDictionary/components/Table/components/BasicCell/basicCell.tsx

@@ -1,12 +1,20 @@
 import { Typography } from "@mui/material";
-import React from "react";
+import { CellContext, RowData } from "@tanstack/react-table";
+import React, { ReactNode } from "react";
 import { TYPOGRAPHY_PROPS } from "../../../../../../styles/common/mui/typography";
-import { BasicCellProps } from "./types";
+import { parseValue } from "./utils";
 
-export const BasicCell = ({ getValue }: BasicCellProps): JSX.Element => {
+export const BasicCell = <
+  T extends RowData,
+  TValue extends ReactNode = ReactNode
+>({
+  getValue,
+}: CellContext<T, TValue>): JSX.Element | null => {
+  const value = getValue();
+  if (value === undefined || value === null) return null;
   return (
     <Typography variant={TYPOGRAPHY_PROPS.VARIANT.INHERIT}>
-      {getValue()}
+      {parseValue(value)}
     </Typography>
   );
 };