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

Author: frano-m

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

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

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

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