@malloy-publisher/sdk 0.0.137 → 0.0.139

package/dist/hooks/useDimensionFilters.d.ts

@@ -0,0 +1,84 @@
+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;
+}
+/**
+ * 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;
+}
+/**
+ * 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 declare function useDimensionFilters(params: UseDimensionFiltersParams): UseDimensionFiltersResult;

package/dist/hooks/useDimensionFiltersFromSpec.d.ts

@@ -0,0 +1,52 @@
+import { DimensionSpec, DimensionValues } from './useDimensionalFilterRangeData';
+import { DimensionFilterState, FilterSelection } from './useDimensionFilters';
+/**
+ * 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 declare function useDimensionFiltersFromSpec(config: DimensionFiltersConfig, queryLimit?: number): {
+    filterStates: Map<string, DimensionFilterState>;
+    updateFilter: (dimensionName: string, selection: FilterSelection | null) => void;
+    clearAllFilters: () => void;
+    activeFilters: FilterSelection[];
+    data: DimensionValues;
+    noRowsMatchedFilter: boolean;
+    isLoading: boolean;
+    isInitialLoading: boolean;
+    isError: boolean;
+    error: Error;
+    refetch: () => void;
+    embeddedQueryResult: string;
+    queryString: string;
+    executeQuery: () => void;
+    canExecute: boolean;
+};

package/dist/hooks/useDimensionFiltersQuery.d.ts

@@ -0,0 +1,79 @@
+import { FilterSelection } from './useDimensionFilters';
+/**
+ * Parameters for the useDimensionFiltersQuery hook
+ */
+export interface UseDimensionFiltersQueryParams {
+    /** Project name */
+    project: string;
+    /** Package name */
+    package: string;
+    /** Model path */
+    model: string;
+    /** Source name within the model */
+    source: string;
+    /** Active filter selections */
+    filterSelections: FilterSelection[];
+    /** Optional fields to select in the query */
+    fields?: string[];
+    /** Maximum number of results to return (default: 1000) */
+    limit?: number;
+}
+/**
+ * Result from the useDimensionFiltersQuery hook
+ */
+export interface DimensionFiltersQueryResult {
+    /** Embedded query result string suitable for rendering with EmbeddedQueryResult */
+    embeddedQueryResult: string | null;
+    /** The generated Malloy query string (preview only, not executed) */
+    queryString: string;
+    /** The resource URI for the model */
+    resourceUri: string;
+    /** Function to execute the query and generate the embedded result */
+    executeQuery: () => void;
+    /** Whether a query can be executed (has filter selections) */
+    canExecute: boolean;
+}
+/**
+ * Custom hook to generate an embedded Malloy query with dimensional filters
+ *
+ * This hook takes filter selections from useDimensionFilters, builds a complete
+ * Malloy query with WHERE clauses, and provides a function to execute the query
+ * and create an embedded query result string that can be rendered with the
+ * EmbeddedQueryResult component.
+ *
+ * The query is not executed automatically - you must call executeQuery() to
+ * generate the embedded result.
+ *
+ * @param params - Parameters including model info, source, and filter selections
+ * @returns Query metadata, embedded result, and execute function
+ *
+ * @example
+ * ```tsx
+ * const { filterStates, getActiveFilters } = useDimensionFilters({
+ *   dimensionSpecs: [
+ *     { dimensionName: "category", filterType: "Star", source: "my_source", model: "model.malloy" },
+ *   ],
+ * });
+ *
+ * const { embeddedQueryResult, executeQuery, canExecute } = useDimensionFiltersQuery({
+ *   project: "my-project",
+ *   package: "my-package",
+ *   model: "model.malloy",
+ *   source: "my_source",
+ *   filterSelections: getActiveFilters(),
+ *   fields: ["category", "price", "quantity"],
+ *   limit: 1000, // Optional: defaults to 1000
+ * });
+ *
+ * // Execute button
+ * <Button onClick={executeQuery} disabled={!canExecute}>
+ *   Execute Query
+ * </Button>
+ *
+ * // Render with EmbeddedQueryResult component
+ * {embeddedQueryResult && (
+ *   <EmbeddedQueryResult embeddedQueryResult={embeddedQueryResult} />
+ * )}
+ * ```
+ */
+export declare function useDimensionFiltersQuery(params: UseDimensionFiltersQueryParams): DimensionFiltersQueryResult;

package/dist/hooks/useDimensionalFilterRangeData.d.ts

@@ -0,0 +1,106 @@
+import { FilterSelection, FilterValuePrimitive } from './useDimensionFilters';
+/**
+ * Filter types for dimensions
+ */
+export type FilterType = "NONE" | "Star" | "MinMax" | "DateMinMax" | "Retrieval" | "Boolean";
+/**
+ * Specification for a dimension to filter
+ */
+export interface DimensionSpec {
+    /** Name of the dimension field */
+    dimensionName: string;
+    /** Type of filter to apply */
+    filterType: FilterType;
+    /** Source name within the model */
+    source: string;
+    /** Model path */
+    model: string;
+    /** Minimum similarity score for Retrieval filter type (default: 0.1) */
+    minSimilarityScore?: number;
+    /** Optional list of static values to use for the dropdown instead of querying */
+    values?: string[];
+}
+/**
+ * Value information for a dimension
+ */
+export interface DimensionValue {
+    value: FilterValuePrimitive;
+    count?: number;
+}
+/**
+ * Result type mapping dimension names to their values
+ */
+export type DimensionValues = Map<string, DimensionValue[]>;
+/**
+ * Parameters for the useDimensionalFilterRangeData hook
+ */
+export interface UseDimensionalFilterRangeDataParams {
+    /** Project name */
+    project: string;
+    /** Package name */
+    package: string;
+    /** List of dimension specifications (each includes source and model) */
+    dimensionSpecs: DimensionSpec[];
+    /** Version ID (optional) */
+    versionId?: string;
+    /** Whether the query should be enabled */
+    enabled?: boolean;
+    /** Maximum number of index results to return (default: 1000) */
+    indexLimit?: number;
+    /** Active filter selections to apply when fetching dimension values (optional) */
+    activeFilters?: FilterSelection[];
+}
+/**
+ * Result from the useDimensionalFilterRangeData hook
+ */
+export interface DimensionalFilterRangeDataResult {
+    /** Map of dimension names to their values */
+    data: DimensionValues | undefined;
+    /** Whether no rows matched the filter */
+    noRowsMatchedFilter: boolean;
+    /** Whether the query is loading */
+    isLoading: boolean;
+    /** Whether the query encountered an error */
+    isError: boolean;
+    /** Error object if query failed */
+    error: Error | null;
+    /** Refetch function to manually trigger the query */
+    refetch: () => void;
+}
+/**
+ * Custom hook to fetch dimensional filter values from a Malloy model
+ *
+ * This hook uses Malloy's built-in `index` operator to create dimensional search indexes
+ * for the specified dimensions. The index operator efficiently returns distinct values
+ * and ranges for dimensions in a single query.
+ *
+ * Filter types:
+ * - NONE: Display only, no values fetched
+ * - Star: Fetches all distinct values with counts (for string fields)
+ * - MinMax: Fetches minimum and maximum values (for numeric fields as ranges)
+ * - DateMinMax: Fetches minimum and maximum values (for date fields as Date objects)
+ * - Retrieval: Uses retrieval, no values fetched
+ *
+ * Reference: https://docs.malloydata.dev/documentation/patterns/dim_index
+ *
+ * The hook groups dimension specs by source/model combination and runs separate
+ * index queries for each group, then merges the results.
+ *
+ * @param params - Parameters including project, package, and dimension specs (each with source/model)
+ * @returns Query result with dimension values map, loading state, and error information
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error } = useDimensionalFilterRangeData({
+ *   project: "my-project",
+ *   package: "my-package",
+ *   dimensionSpecs: [
+ *     { dimensionName: "category", filterType: "Star", source: "my_source", model: "model.malloy" },
+ *     { dimensionName: "price", filterType: "MinMax", source: "my_source", model: "model.malloy" },
+ *     { dimensionName: "status", filterType: "Star", source: "other_source", model: "other.malloy" },
+ *   ],
+ *   indexLimit: 1000, // Optional: set higher if needed for many Star dimensions
+ * });
+ * ```
+ */
+export declare function useDimensionalFilterRangeData(params: UseDimensionalFilterRangeDataParams): DimensionalFilterRangeDataResult;