@malloy-publisher/sdk 0.0.138 → 0.0.140

package/dist/components/filter/DimensionFilter.d.ts

@@ -0,0 +1,43 @@
+import { DimensionSpec, DimensionValue } from '../../hooks/useDimensionalFilterRangeData';
+import { FilterSelection } from '../../hooks/useDimensionFilters';
+/**
+ * Type for the retrieval function used by Retrieval filter type
+ */
+export type RetrievalFunction = (query: string, spec: DimensionSpec) => Promise<DimensionValue[]>;
+/**
+ * Props for DimensionFilter component
+ */
+export interface DimensionFilterProps {
+    /** The dimension specification */
+    spec: DimensionSpec;
+    /** Available values for this dimension */
+    values: DimensionValue[];
+    /** Current filter selection (optional) */
+    selection?: FilterSelection | null;
+    /** Callback when filter changes */
+    onChange: (selection: FilterSelection | null) => void;
+    /** Retrieval function for semantic search (required for Retrieval filter type) */
+    retrievalFn?: RetrievalFunction;
+}
+/**
+ * DimensionFilter component - Renders appropriate filter UI based on dimension type
+ *
+ * This component dynamically renders the appropriate filter UI based on the dimension's
+ * filter type and selected match type. It supports:
+ * - Star filters: Dropdown selection or text search
+ * - MinMax filters: Numeric input with comparison operators
+ * - DateMinMax filters: Date pickers with date comparison operators
+ *
+ * @param props - Component props including spec, values, selection, and onChange callback
+ *
+ * @example
+ * ```tsx
+ * <DimensionFilter
+ *   spec={{ dimensionName: "category", filterType: "Star" }}
+ *   values={categoryValues}
+ *   selection={currentSelection}
+ *   onChange={(selection) => updateFilter("category", selection)}
+ * />
+ * ```
+ */
+export declare function DimensionFilter({ spec, values, selection, onChange, retrievalFn, }: DimensionFilterProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/filter/index.d.ts

@@ -0,0 +1,4 @@
+export { DimensionFilter } from './DimensionFilter';
+export type { DimensionFilterProps, RetrievalFunction, } from './DimensionFilter';
+export { extractDimensionSpecs, extractSourceFromQuery, generateFilterClause, getJoinedSources, injectWhereClause, parseAllSourceInfos, parseDimensionFilterAnnotation, parseNotebookFilterAnnotation, } from './utils';
+export type { DimensionFilterAnnotation, FilterSpec, NotebookFilterConfig, } from './utils';

package/dist/components/filter/utils.d.ts

@@ -0,0 +1,75 @@
+import { DimensionSpec, FilterType } from '../../hooks/useDimensionalFilterRangeData';
+import { FilterSelection } from '../../hooks/useDimensionFilters';
+import * as Malloy from "@malloydata/malloy-interfaces";
+/**
+ * A single filter specification with source and dimension
+ * Parsed from "source.dimension" string format
+ */
+export interface FilterSpec {
+    source: string;
+    dimension: string;
+}
+/**
+ * Configuration parsed from notebook ##(filter) annotation
+ */
+export interface NotebookFilterConfig {
+    filters: FilterSpec[];
+}
+/**
+ * Filter annotation parsed from dimension #(filter) tag
+ */
+export interface DimensionFilterAnnotation {
+    type: FilterType;
+}
+/**
+ * Get the names of all sources that are joined into a given source
+ * Looks for fields with kind: "join" in the SourceInfo
+ */
+export declare function getJoinedSources(sourceInfo: Malloy.SourceInfo): Set<string>;
+/**
+ * Parse ##(filter) annotation from notebook annotations
+ * Format: ##(filters) ["source.dimension", "source2.dimension2", ...]
+ * Returns the filter config or null if not found
+ */
+export declare function parseNotebookFilterAnnotation(annotations: string[] | undefined): NotebookFilterConfig | null;
+/**
+ * Parse #(filter) annotation from a dimension annotation string
+ * Returns the filter annotation or null if not found
+ */
+export declare function parseDimensionFilterAnnotation(annotation: string): DimensionFilterAnnotation | null;
+/**
+ * Parse all source infos from notebook cells and create a map of source_name -> SourceInfo
+ * Also returns the model path from the first import statement found
+ */
+export declare function parseAllSourceInfos(cells: Array<{
+    type?: string;
+    newSources?: string[];
+    text?: string;
+}>): {
+    sourceInfoMap: Map<string, Malloy.SourceInfo>;
+    modelPath: string;
+};
+/**
+ * Extract dimension specs from SourceInfo map based on filter specs from notebook annotation
+ * Looks for #(filter) annotations on the dimensions to determine filter types
+ * Each spec includes source and model for proper query routing
+ */
+export declare function extractDimensionSpecs(sourceInfoMap: Map<string, Malloy.SourceInfo>, filterSpecs: FilterSpec[], modelPath: string): DimensionSpec[];
+/**
+ * Generate a Malloy WHERE clause filter string from filter selections
+ * Uses source.dimension format only for joined sources (not the query's main source)
+ */
+export declare function generateFilterClause(activeFilters: FilterSelection[], dimensionToSourceMap: Map<string, string>, querySourceName: string | null): string;
+/**
+ * Extract the source name from a Malloy query
+ * Handles patterns like:
+ * - "run: source_name -> ..."
+ * - "run: source_name->view_name"
+ * Returns null if no source name can be extracted
+ */
+export declare function extractSourceFromQuery(query: string): string | null;
+/**
+ * Injects a where clause into a Malloy query by appending "+ {where: ...}"
+ * Uses Malloy's refinement syntax which works with any query pattern.
+ */
+export declare function injectWhereClause(query: string, filterClause: string): string;

package/dist/components/index.d.ts

@@ -1,14 +1,15 @@
+export { AnalyzePackageButton } from './AnalyzePackageButton';
+export { useRouterClickHandler } from './click_helper';
+export * from './filter';
+export * from './Home';
+export * from './Loading';
 export * from './Model';
 export * from './Notebook';
-export * from './Workbook';
 export * from './Package';
 export * from './Project';
 export * from './QueryResult';
-export * from './Home';
-export * from './Loading';
-export { useRouterClickHandler } from './click_helper';
+export * from './RenderedResult';
 export { ServerProvider, useServer } from './ServerProvider';
 export type { ServerContextValue, ServerProviderProps } from './ServerProvider';
-export { AnalyzePackageButton } from './AnalyzePackageButton';
+export * from './Workbook';
 export type { WorkbookStorage } from './Workbook';
-export * from './RenderedResult';

package/dist/components/styles.d.ts

@@ -3,9 +3,9 @@ import { CardOwnProps, Theme, CardContentOwnProps, CardMediaOwnProps } from '@mu
 import { CommonProps } from '@mui/material/OverridableComponent';
 import { DetailedHTMLProps, HTMLAttributes } from 'react';
 import { MUIStyledCommonProps } from '@mui/system';
-export declare const StyledCard: StyledComponent< CardOwnProps & CommonProps & Omit< DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "className" | "style" | "classes" | "children" | "sx" | "variant" | "square" | "elevation" | "raised"> & MUIStyledCommonProps<Theme>, {}, {}>;
+export declare const StyledCard: StyledComponent< CardOwnProps & CommonProps & Omit< DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "className" | "style" | "classes" | "children" | "elevation" | "square" | "sx" | "variant" | "raised"> & MUIStyledCommonProps<Theme>, {}, {}>;
 export declare const StyledCardContent: StyledComponent< CardContentOwnProps & CommonProps & Omit< DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "className" | "style" | "classes" | "children" | "sx"> & MUIStyledCommonProps<Theme>, {}, {}>;
-export declare const StyledCardMedia: StyledComponent< CardMediaOwnProps & CommonProps & Omit< DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "className" | "style" | "classes" | "children" | "sx" | "image" | "src"> & MUIStyledCommonProps<Theme>, {}, {}>;
+export declare const StyledCardMedia: StyledComponent< CardMediaOwnProps & CommonProps & Omit< DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "className" | "style" | "classes" | "image" | "children" | "sx" | "src"> & MUIStyledCommonProps<Theme>, {}, {}>;
 export declare const CleanNotebookContainer: StyledComponent<MUIStyledCommonProps<Theme>, DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const CleanNotebookHeader: StyledComponent<MUIStyledCommonProps<Theme>, DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const CleanNotebookSection: StyledComponent<MUIStyledCommonProps<Theme>, DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
@@ -17,7 +17,7 @@ export declare const StyledExplorerPage: StyledComponent<MUIStyledCommonProps<Th
 export declare const StyledExplorerBanner: StyledComponent<MUIStyledCommonProps<Theme>, DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const StyledExplorerContent: StyledComponent<MUIStyledCommonProps<Theme>, DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const StyledExplorerPanel: StyledComponent<MUIStyledCommonProps<Theme>, DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
-export declare const PackageCard: StyledComponent< CardOwnProps & CommonProps & Omit< DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "className" | "style" | "classes" | "children" | "sx" | "variant" | "square" | "elevation" | "raised"> & MUIStyledCommonProps<Theme>, {}, {}>;
+export declare const PackageCard: StyledComponent< CardOwnProps & CommonProps & Omit< DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "className" | "style" | "classes" | "children" | "elevation" | "square" | "sx" | "variant" | "raised"> & MUIStyledCommonProps<Theme>, {}, {}>;
 export declare const PackageCardContent: StyledComponent< CardContentOwnProps & CommonProps & Omit< DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "className" | "style" | "classes" | "children" | "sx"> & MUIStyledCommonProps<Theme>, {}, {}>;
 export declare const PackageSectionTitle: StyledComponent<MUIStyledCommonProps<Theme>, DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
 export declare const PackageContainer: StyledComponent<MUIStyledCommonProps<Theme>, DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/dist/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export { useDimensionFilters, type DimensionFilterState, type FilterSelection, type MatchType, type UseDimensionFiltersParams, type UseDimensionFiltersResult, } from './useDimensionFilters';
+export { useDimensionFiltersFromSpec, type DimensionFiltersConfig, type UseDimensionFiltersFromSpecOptions, } from './useDimensionFiltersFromSpec';
+export { useDimensionFiltersQuery, type DimensionFiltersQueryResult, type UseDimensionFiltersQueryParams, } from './useDimensionFiltersQuery';
+export { useDimensionalFilterRangeData, type DimensionalFilterRangeDataResult, type DimensionSpec, type DimensionValue, type DimensionValues, type FilterType, type UseDimensionalFilterRangeDataParams, } from './useDimensionalFilterRangeData';

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;