feat!: implement filter range in category filters (#440)

Author: Fran McDade

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;
+}

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);
+}

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 === undefined || typeof v === "number")
+  );
+}

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 | undefined;
+  min: number | undefined;
+  selectedMax: SelectedRange[1];
+  selectedMin: SelectedRange[0];
+}
+
+/**
+ * Min and max values selected in range category.
+ */
+export type SelectedRange = [number?, number?];

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

@@ -0,0 +1,29 @@
+import { 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 a selected range");
+  }
+}
+
+/**
+ * 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
+    : [];
+}

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;

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;
+}

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;
+}

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 | undefined;
+  min: number | undefined;
+  selectedMax: SelectedRange[1];
+  selectedMin: SelectedRange[0];
+  unit?: string;
+}
+
+/**
+ * Model of range category view kind.
+ */
+export interface RangeViewKind {
+  viewKind: VIEW_KIND.RANGE;
+}

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,
+  };
+}