@malloy-publisher/sdk 0.0.137 → 0.0.139

package/src/hooks/useDimensionFilters.ts

@@ -0,0 +1,322 @@
+import { useCallback, useEffect, useState } from "react";
+import { DimensionSpec } from "./useDimensionalFilterRangeData";
+
+/**
+ * Match types for filtering dimensions
+ */
+export type MatchType =
+   | "Equals"
+   | "Contains"
+   | "After"
+   | "Before"
+   | "Less Than"
+   | "Greater Than"
+   | "Between"
+   | "Concept Search";
+
+/**
+ * Primitive types that can be used as filter values
+ */
+export type FilterValuePrimitive = string | number | boolean | Date;
+
+/**
+ * Type for filter values - can be a single value or an array for multi-select
+ */
+export type FilterValue = FilterValuePrimitive | FilterValuePrimitive[];
+
+/**
+ * A selected filter value with its match type
+ */
+export interface FilterSelection {
+   dimensionName: string;
+   matchType: MatchType;
+   value: FilterValue;
+   value2?: FilterValuePrimitive; // For "Between" match type
+}
+
+/**
+ * Complete filter state including the dimension spec and selection
+ */
+export interface DimensionFilterState {
+   spec: DimensionSpec;
+   selection: FilterSelection | null;
+}
+
+/**
+ * Parameters for the useDimensionFilters hook
+ */
+export interface UseDimensionFiltersParams {
+   /** Dimension specifications (each includes source and model) */
+   dimensionSpecs: DimensionSpec[];
+}
+
+/**
+ * Result from the useDimensionFilters hook
+ */
+export interface UseDimensionFiltersResult {
+   /** Current filter states */
+   filterStates: Map<string, DimensionFilterState>;
+   /** Update a filter selection */
+   updateFilter: (
+      dimensionName: string,
+      selection: FilterSelection | null,
+   ) => void;
+   /** Clear a specific filter */
+   clearFilter: (dimensionName: string) => void;
+   /** Clear all filters */
+   clearAllFilters: () => void;
+   /** Get active filters (with selections) */
+   getActiveFilters: () => FilterSelection[];
+   /** Generate Malloy query fragment for active filters */
+   generateWhereClause: () => string;
+}
+
+/**
+ * Escapes special characters in strings for Malloy queries
+ */
+function escapeMalloyString(value: string): string {
+   return value.replace(/'/g, "\\'").replace(/\\/g, "\\\\");
+}
+
+/**
+ * Formats a value for use in Malloy query
+ */
+function formatMalloyValue(
+   value: FilterValuePrimitive | null | undefined,
+   isDate: boolean = false,
+): string {
+   if (value === null || value === undefined) {
+      return "null";
+   }
+
+   if (isDate) {
+      if (value instanceof Date) {
+         // Format as YYYY-MM-DD
+         return `@${value.getFullYear()}-${String(value.getMonth() + 1).padStart(2, "0")}-${String(value.getDate()).padStart(2, "0")}`;
+      }
+      // If it's a string, assume it's already in ISO format
+      return `@${value}`;
+   }
+
+   if (typeof value === "string") {
+      return `'${escapeMalloyString(value)}'`;
+   }
+
+   if (typeof value === "number") {
+      return String(value);
+   }
+
+   if (typeof value === "boolean") {
+      return value ? "true" : "false";
+   }
+
+   return String(value);
+}
+
+/**
+ * Generates a Malloy filter condition for a single filter selection
+ */
+function generateFilterCondition(selection: FilterSelection): string {
+   const { dimensionName, matchType, value, value2 } = selection;
+   const fieldName = `\`${dimensionName}\``;
+
+   // Determine if this is a date field based on the value
+   const isDate = value instanceof Date;
+
+   switch (matchType) {
+      case "Equals":
+      case "Concept Search":
+         if (Array.isArray(value) && value.length > 0) {
+            // Handle multi-select: (field = val1 or field = val2)
+            const conditions = value.map(
+               (v) => `${fieldName} = ${formatMalloyValue(v, isDate)}`,
+            );
+            return `(${conditions.join(" or ")})`;
+         }
+         // Empty array or single value
+         if (Array.isArray(value)) return "";
+         return `${fieldName} = ${formatMalloyValue(value, isDate)}`;
+
+      case "Contains":
+         if (typeof value === "string") {
+            return `${fieldName} ~ f'%${escapeMalloyString(value)}%'`;
+         }
+         if (Array.isArray(value)) return "";
+         return `${fieldName} = ${formatMalloyValue(value)}`;
+
+      case "After":
+         if (Array.isArray(value)) return "";
+         return `${fieldName} > ${formatMalloyValue(value, isDate)}`;
+
+      case "Before":
+         if (Array.isArray(value)) return "";
+         return `${fieldName} < ${formatMalloyValue(value, isDate)}`;
+
+      case "Greater Than":
+         if (Array.isArray(value)) return "";
+         return `${fieldName} > ${formatMalloyValue(value)}`;
+
+      case "Less Than":
+         if (Array.isArray(value)) return "";
+         return `${fieldName} < ${formatMalloyValue(value)}`;
+
+      case "Between":
+         if (Array.isArray(value)) return "";
+         if (value2 !== undefined) {
+            return `${fieldName} >= ${formatMalloyValue(value, isDate)} and ${fieldName} <= ${formatMalloyValue(value2, isDate)}`;
+         }
+         return `${fieldName} >= ${formatMalloyValue(value, isDate)}`;
+
+      default:
+         return "";
+   }
+}
+
+/**
+ * Custom hook to manage dimension filter state and generate Malloy queries
+ *
+ * This hook maintains filter state for multiple dimensions and provides utilities
+ * to generate Malloy WHERE clauses based on the active filters.
+ *
+ * @param params - Parameters including dimension specs (each with source and model)
+ * @returns Filter state management functions and query generation
+ *
+ * @example
+ * ```tsx
+ * const { filterStates, updateFilter, generateWhereClause } = useDimensionFilters({
+ *   dimensionSpecs: [
+ *     { dimensionName: "category", filterType: "Star", source: "my_source", model: "model.malloy" },
+ *     { dimensionName: "price", filterType: "MinMax", source: "my_source", model: "model.malloy" },
+ *   ],
+ * });
+ *
+ * // Update a filter
+ * updateFilter("category", {
+ *   dimensionName: "category",
+ *   matchType: "Equals",
+ *   value: "Electronics"
+ * });
+ *
+ * // Generate query
+ * const whereClause = generateWhereClause();
+ * // Returns: "where `category` = 'Electronics'"
+ * ```
+ */
+export function useDimensionFilters(
+   params: UseDimensionFiltersParams,
+): UseDimensionFiltersResult {
+   const { dimensionSpecs } = params;
+
+   // Initialize filter states
+   const [filterStates, setFilterStates] = useState<
+      Map<string, DimensionFilterState>
+   >(() => {
+      const initialStates = new Map<string, DimensionFilterState>();
+      dimensionSpecs.forEach((spec) => {
+         initialStates.set(spec.dimensionName, {
+            spec,
+            selection: null,
+         });
+      });
+      return initialStates;
+   });
+
+   // Sync filter states when dimensionSpecs change (e.g., loaded asynchronously)
+   useEffect(() => {
+      setFilterStates((prevStates) => {
+         const newStates = new Map<string, DimensionFilterState>();
+
+         dimensionSpecs.forEach((spec) => {
+            // Preserve existing selection if the dimension already exists
+            const existingState = prevStates.get(spec.dimensionName);
+            newStates.set(spec.dimensionName, {
+               spec,
+               selection: existingState?.selection ?? null,
+            });
+         });
+
+         return newStates;
+      });
+   }, [dimensionSpecs]);
+
+   // Update a filter selection
+   const updateFilter = useCallback(
+      (dimensionName: string, selection: FilterSelection | null) => {
+         setFilterStates((prevStates) => {
+            const newStates = new Map(prevStates);
+            const existingState = newStates.get(dimensionName);
+
+            if (existingState) {
+               newStates.set(dimensionName, {
+                  ...existingState,
+                  selection,
+               });
+            }
+
+            return newStates;
+         });
+      },
+      [],
+   );
+
+   // Clear a specific filter
+   const clearFilter = useCallback(
+      (dimensionName: string) => {
+         updateFilter(dimensionName, null);
+      },
+      [updateFilter],
+   );
+
+   // Clear all filters
+   const clearAllFilters = useCallback(() => {
+      setFilterStates((prevStates) => {
+         const newStates = new Map(prevStates);
+         newStates.forEach((state, key) => {
+            newStates.set(key, {
+               ...state,
+               selection: null,
+            });
+         });
+         return newStates;
+      });
+   }, []);
+
+   // Get active filters (those with selections)
+   const getActiveFilters = useCallback((): FilterSelection[] => {
+      const activeFilters: FilterSelection[] = [];
+      filterStates.forEach((state) => {
+         if (state.selection) {
+            activeFilters.push(state.selection);
+         }
+      });
+      return activeFilters;
+   }, [filterStates]);
+
+   // Generate Malloy WHERE clause from active filters
+   const generateWhereClause = useCallback((): string => {
+      const activeFilters = getActiveFilters();
+
+      if (activeFilters.length === 0) {
+         return "";
+      }
+
+      const conditions = activeFilters
+         .map((selection) => generateFilterCondition(selection))
+         .filter((condition) => condition.length > 0);
+
+      if (conditions.length === 0) {
+         return "";
+      }
+
+      return `where ${conditions.join(" and ")}`;
+   }, [getActiveFilters]);
+
+   return {
+      filterStates,
+      updateFilter,
+      clearFilter,
+      clearAllFilters,
+      getActiveFilters,
+      generateWhereClause,
+   };
+}

package/src/hooks/useDimensionFiltersFromSpec.ts

@@ -0,0 +1,117 @@
+import { useMemo } from "react";
+import {
+   DimensionSpec,
+   useDimensionalFilterRangeData,
+} from "./useDimensionalFilterRangeData";
+import { useDimensionFilters } from "./useDimensionFilters";
+import { useDimensionFiltersQuery } from "./useDimensionFiltersQuery";
+
+/**
+ * Configuration for dimensional filters
+ */
+export interface DimensionFiltersConfig {
+   /** Project name */
+   project: string;
+   /** Package name */
+   package: string;
+   /** Version ID (optional) */
+   versionId?: string;
+   /** Index limit for retrieval queries */
+   indexLimit: number;
+   /** Dimension specifications for filters (each includes source and model) */
+   dimensionSpecs: DimensionSpec[];
+   /** Fields/columns to group by in the query (if not specified, uses select *) */
+   selectFields?: string[];
+}
+
+/**
+ * Options passed to useDimensionFiltersFromSpec
+ */
+export interface UseDimensionFiltersFromSpecOptions {
+   config: DimensionFiltersConfig;
+   /** Maximum number of results to return from query (default: 100) */
+   queryLimit?: number;
+}
+
+/**
+ * Combined hook that manages dimensional filters, data fetching, and query execution
+ * from a single configuration object.
+ *
+ * @param config - Configuration containing project, package, dimension specs, and index limit
+ * @param queryLimit - Maximum number of results to return from query (default: 100)
+ * @returns All state and methods needed for dimensional filtering UI
+ */
+export function useDimensionFiltersFromSpec(
+   config: DimensionFiltersConfig,
+   queryLimit: number = 5000,
+) {
+   // Get primary source/model from dimension specs (for query execution)
+   const primarySource = config.dimensionSpecs[0]?.source ?? "";
+   const primaryModel = config.dimensionSpecs[0]?.model ?? "";
+
+   // Manage filter state and query generation
+   const { filterStates, updateFilter, clearAllFilters, getActiveFilters } =
+      useDimensionFilters({
+         dimensionSpecs: config.dimensionSpecs,
+      });
+
+   // Get active filters (memoized to prevent unnecessary re-renders)
+   // Note: filterStates must be in the dependency array to ensure activeFilters updates
+   // when individual filter values change (e.g., removing a chip from multi-select)
+   const activeFilters = useMemo(
+      () => getActiveFilters(),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [filterStates, getActiveFilters],
+   );
+
+   // Fetch dimensional filter range data
+   // When activeFilters change, the hook will automatically re-fetch with filters applied
+   // The hook handles multiple source/model combos internally
+   const { data, noRowsMatchedFilter, isLoading, isError, error, refetch } =
+      useDimensionalFilterRangeData({
+         project: config.project,
+         package: config.package,
+         indexLimit: config.indexLimit,
+         dimensionSpecs: config.dimensionSpecs,
+         versionId: config.versionId,
+         activeFilters,
+      });
+
+   // Only show loading on initial load, not during refetches
+   const isInitialLoading = isLoading && !data;
+
+   // Generate the embedded query result (uses primary source/model)
+   const { embeddedQueryResult, queryString, executeQuery, canExecute } =
+      useDimensionFiltersQuery({
+         project: config.project,
+         package: config.package,
+         model: primaryModel,
+         source: primarySource,
+         filterSelections: activeFilters,
+         limit: queryLimit,
+         fields: config.selectFields,
+      });
+
+   return {
+      // Filter state management
+      filterStates,
+      updateFilter,
+      clearAllFilters,
+      activeFilters,
+
+      // Data fetching
+      data,
+      noRowsMatchedFilter,
+      isLoading,
+      isInitialLoading,
+      isError,
+      error,
+      refetch,
+
+      // Query execution
+      embeddedQueryResult,
+      queryString,
+      executeQuery,
+      canExecute,
+   };
+}