@kronor/dtv 0.2.9

package/src/framework/filter-form-state.ts

@@ -0,0 +1,185 @@
+import { FilterSchemasAndGroups, FilterField, FilterControl, FilterExpr, FilterTransform } from './filters';
+import { FilterState, buildInitialFormState, FormStateInitMode } from './state';
+
+// Tree-like state for FilterForm
+export type FilterFormState =
+    | {
+        type: 'leaf';
+        value: any;
+    }
+    | { type: 'and' | 'or'; children: FilterFormState[] }
+    | { type: 'not'; child: FilterFormState };
+
+/**
+ * Generic helper to apply a transformation function to all leaf values in a FilterFormState tree
+ */
+export function mapFilterFormState<T>(
+    node: FilterFormState,
+    transformValue: (value: any) => T
+): FilterFormState {
+    if (node.type === 'leaf') {
+        return {
+            ...node,
+            value: transformValue(node.value)
+        };
+    } else if (node.type === 'not') {
+        return {
+            type: 'not',
+            child: mapFilterFormState(node.child, transformValue)
+        };
+    } else {
+        return {
+            type: node.type,
+            children: node.children.map(child => mapFilterFormState(child, transformValue))
+        };
+    }
+}
+
+// Type aliases for narrowed FilterExpr types
+type LeafFilterExpr = FilterExpr & { field: FilterField; value: FilterControl; transform?: FilterTransform };
+type AndFilterExpr = FilterExpr & { type: 'and' };
+type OrFilterExpr = FilterExpr & { type: 'or' };
+type NotFilterExpr = FilterExpr & { type: 'not' };
+
+/**
+ * Helper function that recursively traverses both filter schema and state in parallel.
+ * Calls the appropriate handler for each node in the tree based on the state node type.
+ *
+ * This helper is useful for operations that need to correlate schema information with state values,
+ * such as:
+ * - Building query conditions recursively
+ * - Building validation result trees
+ * - Transforming data structures while preserving tree shape
+ * - Building UI components from schema + state
+ *
+ * @param schemaNode - The schema node to traverse
+ * @param stateNode - The state node to traverse
+ * @param handlers - Record of functions keyed by FilterFormState type, each handling specific node types
+ * @returns Single result of type T built recursively
+ */
+export function traverseFilterSchemaAndState<T>(
+    schemaNode: FilterExpr,
+    stateNode: FilterFormState,
+    handlers: {
+        leaf: (schemaNode: LeafFilterExpr, stateNode: FilterFormState & { type: 'leaf' }) => T;
+        and: (schemaNode: AndFilterExpr, stateNode: FilterFormState & { type: 'and' }, childResults: T[]) => T;
+        or: (schemaNode: OrFilterExpr, stateNode: FilterFormState & { type: 'or' }, childResults: T[]) => T;
+        not: (schemaNode: NotFilterExpr, stateNode: FilterFormState & { type: 'not' }, childResult: T) => T;
+    }
+): T {
+    switch (stateNode.type) {
+        case 'leaf':
+            return handlers.leaf(schemaNode as LeafFilterExpr, stateNode as FilterFormState & { type: 'leaf' });
+
+        case 'and': {
+            const state = stateNode as FilterFormState & { type: 'and' };
+            const schema = schemaNode
+            if (schema.type !== 'and') {
+                throw new Error(`Schema type mismatch: expected 'and', got '${schema.type}'`);
+            }
+            // Recursively traverse children
+            const childResults = state.children.map((childState, index) => {
+                const childSchema = schema.filters[index];
+                if (!childSchema) {
+                    throw new Error(`Missing schema for child at index ${index}`);
+                }
+                return traverseFilterSchemaAndState(childSchema, childState, handlers);
+            });
+
+            return handlers.and(schema, state, childResults);
+        }
+
+        case 'or': {
+            const state = stateNode as FilterFormState & { type: 'or' };
+            const schema = schemaNode
+            if (schema.type !== 'or') {
+                throw new Error(`Schema type mismatch: expected 'or', got '${schema.type}'`);
+            }
+            // Recursively traverse children
+            const childResults = state.children.map((childState, index) => {
+                const childSchema = schema.filters[index];
+                if (!childSchema) {
+                    throw new Error(`Missing schema for child at index ${index}`);
+                }
+                return traverseFilterSchemaAndState(childSchema, childState, handlers);
+            });
+
+            return handlers.or(schema, state, childResults);
+        }
+
+        case 'not': {
+            const state = stateNode as FilterFormState & { type: 'not' };
+            const schema = schemaNode
+            if (schema.type !== 'not') {
+                throw new Error(`Schema type mismatch: expected 'not', got '${schema.type}'`);
+            }
+            // Recursively traverse the child
+            const childResult = traverseFilterSchemaAndState(schema.filter, state.child, handlers);
+            return handlers.not(schema, state, childResult);
+        }
+
+        default:
+            throw new Error(`Unknown state node type: ${(stateNode)}`);
+    }
+}
+
+/**
+ * Helper to serialize a FilterFormState node, converting Date objects to ISO strings
+ */
+export function makeFilterFormStateSerializable(node: FilterFormState): FilterFormState {
+    return mapFilterFormState(node, (value) => {
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        return value;
+    });
+}
+
+/**
+ * Serialize a FilterState Map to JSON object for storage
+ */
+export function serializeFilterFormStateMap(state: FilterState): Record<string, any> {
+    return Object.fromEntries(
+        Array.from(state.entries())
+            .map(([id, node]) => [id, makeFilterFormStateSerializable(node)])
+    );
+}
+
+/**
+ * Rehydrate a single filter's stored state using its schema expression.
+ * Safely returns the original node on any mismatch / error.
+ */
+function rehydrateFilterStateForSchema(expression: FilterExpr, stored: FilterFormState): FilterFormState {
+    return traverseFilterSchemaAndState<FilterFormState>(expression, stored, {
+        leaf: (schemaLeaf, stateLeaf) => {
+            let value = stateLeaf.value;
+            if (schemaLeaf.value.type === 'date' && typeof value === 'string') {
+                const date = new Date(value);
+                if (!isNaN(date.getTime())) {
+                    value = date;
+                }
+            }
+            return { type: 'leaf', value };
+        },
+        and: (_schemaAnd, _stateAnd, childResults) => ({ type: 'and', children: childResults }),
+        or: (_schemaOr, _stateOr, childResults) => ({ type: 'or', children: childResults }),
+        not: (_schemaNot, _stateNot, childResult) => ({ type: 'not', child: childResult })
+    });
+}
+
+/**
+ * Parse serialized filter state (object keyed by filter id) back into a FilterState Map,
+ * converting date string values to Date objects by consulting the filter schema.
+ */
+export function parseFilterFormState(serializedState: any, schema: FilterSchemasAndGroups): FilterState {
+    return new Map(
+        schema.filters.map(filter => {
+            const raw = serializedState ? serializedState[filter.id] : undefined;
+            if (raw && typeof raw === 'object' && 'type' in raw) {
+                return [filter.id, rehydrateFilterStateForSchema(filter.expression, raw as FilterFormState)] as [string, FilterFormState];
+            }
+            // If invalid/missing, fall back to an empty initialized state derived from schema
+            return [filter.id, buildInitialFormState(filter.expression, FormStateInitMode.Empty)] as [string, FilterFormState];
+        })
+    );
+}

package/src/framework/filter-sharing.test.ts

@@ -0,0 +1,135 @@
+/**
+ * @jest-environment jsdom
+ */
+import {
+    encodeFilterState,
+    decodeFilterState
+} from './filter-sharing';
+import { FilterState } from './state';
+
+describe('filter-sharing', () => {
+    const mockFilterState: FilterState = new Map([
+        ['name-filter', {
+            type: 'leaf',
+            field: 'name',
+            value: 'test',
+            control: { type: 'text' },
+            filterType: 'equals'
+        }],
+        ['date-filter', {
+            type: 'leaf',
+            field: 'date',
+            value: new Date('2023-01-01'),
+            control: { type: 'date' },
+            filterType: 'greaterThanOrEqual'
+        }]
+    ]);
+
+    describe('encodeFilterState', () => {
+        it('should encode filter state to base64 URL-safe string', () => {
+            const encoded = encodeFilterState(mockFilterState);
+
+            expect(typeof encoded).toBe('string');
+            expect(encoded.length).toBeGreaterThan(0);
+            // Should not contain URL-unsafe characters
+            expect(encoded).not.toMatch(/[+/=]/);
+        });
+
+        it('should handle empty filter state', () => {
+            const encoded = encodeFilterState(new Map());
+            expect(typeof encoded).toBe('string');
+        });
+
+        it('should handle complex nested filters', () => {
+            const complexFilter: FilterState = new Map([
+                ['complex-filter', {
+                    type: 'and',
+                    children: [
+                        {
+                            type: 'leaf',
+                            field: 'name',
+                            value: 'test',
+                            control: { type: 'text' },
+                            filterType: 'equals'
+                        },
+                        {
+                            type: 'not',
+                            child: {
+                                type: 'leaf',
+                                field: 'status',
+                                value: 'inactive',
+                                control: { type: 'text' },
+                                filterType: 'equals'
+                            },
+                            filterType: 'not'
+                        }
+                    ],
+                    filterType: 'and'
+                }]
+            ]);
+
+            expect(() => encodeFilterState(complexFilter)).not.toThrow();
+        });
+    });
+
+    describe('decodeFilterState', () => {
+        it('should decode base64 string back to filter state', () => {
+            const encoded = encodeFilterState(mockFilterState);
+            const decoded = decodeFilterState(encoded);
+
+            expect(typeof decoded).toBe('object');
+            expect(decoded).not.toBeNull();
+            expect(Array.isArray(decoded)).toBe(false);
+            expect(Object.keys(decoded)).toHaveLength(2);
+        });
+
+        it('should handle invalid base64 strings', () => {
+            // Mock console.error to suppress expected error output in tests
+            const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+
+            expect(() => decodeFilterState('invalid-base64')).toThrow();
+
+            // Restore console.error
+            consoleSpy.mockRestore();
+        });
+
+        it('should handle empty string', () => {
+            // Mock console.error to suppress expected error output in tests
+            const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+
+            expect(() => decodeFilterState('')).toThrow();
+
+            // Restore console.error
+            consoleSpy.mockRestore();
+        });
+    });
+
+    describe('round-trip encoding/decoding', () => {
+        it('should preserve filter state through encode/decode cycle', () => {
+            const encoded = encodeFilterState(mockFilterState);
+            const decoded: any = decodeFilterState(encoded);
+
+            // The decoded state should be an object with filter ID keys
+            expect(typeof decoded).toBe('object');
+            expect(Array.isArray(decoded)).toBe(false);
+            expect(Object.keys(decoded)).toHaveLength(2);
+
+            // Check that both filters are present with their correct data
+            expect(decoded['name-filter']).toEqual({
+                type: 'leaf',
+                field: 'name',
+                value: 'test',
+                control: { type: 'text' },
+                filterType: 'equals'
+            });
+
+            expect(decoded['date-filter']).toEqual({
+                type: 'leaf',
+                field: 'date',
+                value: '2023-01-01T00:00:00.000Z', // Date serialized as ISO string
+                control: { type: 'date' },
+                filterType: 'greaterThanOrEqual'
+            });
+        });
+    });
+});

package/src/framework/filter-sharing.ts

@@ -0,0 +1,118 @@
+import { serializeFilterFormStateMap } from './filter-form-state';
+import { FilterState } from './state';
+
+/**
+ * Encode filter state to a base64 URL-safe string
+ */
+export function encodeFilterState(filterState: FilterState): string {
+    try {
+        const serializedState = serializeFilterFormStateMap(filterState);
+        const jsonString = JSON.stringify(serializedState);
+        // Convert to base64 and make it URL-safe
+        return btoa(jsonString)
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=/g, '');
+    } catch (error) {
+        console.error('Failed to encode filter state:', error);
+        throw new Error('Failed to encode filter state');
+    }
+}
+
+/**
+ * Decode filter state from a base64 URL-safe string
+ */
+export function decodeFilterState(encodedState: string): any[] {
+    try {
+        // Restore base64 padding and convert back from URL-safe
+        const base64 = encodedState
+            .replace(/-/g, '+')
+            .replace(/_/g, '/')
+            .padEnd(encodedState.length + (4 - encodedState.length % 4) % 4, '=');
+
+        const jsonString = atob(base64);
+        return JSON.parse(jsonString);
+    } catch (error) {
+        console.error('Failed to decode filter state:', error);
+        throw new Error('Failed to decode filter state');
+    }
+}
+
+/**
+ * Create a shareable URL with the current filter state
+ */
+const FILTER_PARAM = 'dtv-filter-state';
+
+export function createShareableUrl(filterState: FilterState): string {
+    try {
+        const encodedFilter = encodeFilterState(filterState);
+        const url = new URL(window.location.href);
+        url.searchParams.set(FILTER_PARAM, encodedFilter);
+        return url.toString();
+    } catch (error) {
+        console.error('Failed to create shareable URL:', error);
+        throw new Error('Failed to create shareable URL');
+    }
+}
+
+/**
+ * Copy URL to clipboard
+ */
+export async function copyToClipboard(text: string): Promise<void> {
+    try {
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+            await navigator.clipboard.writeText(text);
+        } else {
+            // Fallback for older browsers
+            const textArea = document.createElement('textarea');
+            textArea.value = text;
+            textArea.style.position = 'fixed';
+            textArea.style.opacity = '0';
+            document.body.appendChild(textArea);
+            textArea.focus();
+            textArea.select();
+            document.execCommand('copy');
+            document.body.removeChild(textArea);
+        }
+    } catch (error) {
+        console.error('Failed to copy to clipboard:', error);
+        throw new Error('Failed to copy to clipboard');
+    }
+}
+
+/**
+ * Get filter state from URL parameters
+ */
+export function getFilterFromUrl(): any[] | null {
+    try {
+        const params = new URLSearchParams(window.location.search);
+        const encodedFilter = params.get(FILTER_PARAM);
+        if (!encodedFilter) return null;
+        return decodeFilterState(encodedFilter);
+    } catch (error) {
+        console.warn('Failed to parse filter from URL:', error);
+        return null;
+    }
+}
+
+/**
+ * Remove filter parameter from URL without page reload
+ */
+export function clearFilterFromUrl(): void {
+    const url = new URL(window.location.href);
+    url.searchParams.delete(FILTER_PARAM);
+    window.history.replaceState({}, '', url.toString());
+}
+
+export function setFilterInUrl(filterState: FilterState): void {
+    try {
+        const encoded = encodeFilterState(filterState);
+        const url = new URL(window.location.href);
+        if (url.searchParams.get(FILTER_PARAM) !== encoded) {
+            url.searchParams.set(FILTER_PARAM, encoded);
+            window.history.replaceState({}, '', url.toString());
+        }
+    } catch (e) {
+        console.warn('Failed to set filter in URL', e);
+    }
+}

package/src/framework/filters.ts

@@ -0,0 +1,194 @@
+import * as React from 'react';
+
+// Multi-field specification
+export type FilterField =
+    | string  // Single field: "name" or "user.email"
+    | { and: string[] }  // AND multiple fields: { and: ["name", "title", "description"] }
+    | { or: string[] };  // OR multiple fields: { or: ["name", "title", "description"] }
+
+// Transform result type - must return an object with optional field/value fields
+export type TransformResult = { field?: string; value?: unknown };
+
+// Transform functions for filter expressions
+export type FilterTransform = {
+    toQuery?: (input: unknown) => TransformResult;
+};
+
+export type FilterControl =
+    | { type: 'text'; label?: string; placeholder?: string; initialValue?: any }
+    | { type: 'number'; label?: string; placeholder?: string; initialValue?: any }
+    | { type: 'date'; label?: string; placeholder?: string; initialValue?: any }
+    | { type: 'dropdown'; label?: string; items: { label: string; value: any }[]; initialValue?: any }
+    | { type: 'multiselect'; label?: string; items: { label: string; value: any }[], filterable?: boolean; initialValue?: any }
+    | { type: 'customOperator'; label?: string; operators: { label: string; value: string }[]; valueControl: FilterControl; initialValue?: any }
+    | { type: 'custom'; component: React.ComponentType<any>; props?: Record<string, any>; label?: string; initialValue?: any };
+
+export type FilterExpr =
+    | { type: 'equals'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'notEquals'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'greaterThan'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'lessThan'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'greaterThanOrEqual'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'lessThanOrEqual'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'in'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'notIn'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'like'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'iLike'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'isNull'; field: FilterField; value: FilterControl; transform?: FilterTransform }
+    | { type: 'and'; filters: FilterExpr[] }
+    | { type: 'or'; filters: FilterExpr[] }
+    | { type: 'not'; filter: FilterExpr };
+
+
+
+// Predefined list of supported operators for customOperator controls
+export const SUPPORTED_OPERATORS = [
+    { label: 'equals', value: '_eq' },
+    { label: 'not equals', value: '_neq' },
+    { label: 'greater than', value: '_gt' },
+    { label: 'less than', value: '_lt' },
+    { label: 'greater than or equal', value: '_gte' },
+    { label: 'less than or equal', value: '_lte' },
+    { label: 'in', value: '_in' },
+    { label: 'not in', value: '_nin' },
+    { label: 'like', value: '_like' },
+    { label: 'ilike', value: '_ilike' },
+    { label: 'is null', value: '_is_null' }
+];
+
+// Helper functions for building FilterControl values
+export const filterControl = {
+    text: (options?: { label?: string; placeholder?: string }): FilterControl => ({ type: 'text', ...options }),
+    number: (options?: { label?: string; placeholder?: string; initialValue?: any }): FilterControl => ({ type: 'number', ...options }),
+    date: (options?: { label?: string; placeholder?: string; initialValue?: any }): FilterControl => ({ type: 'date', ...options }),
+    dropdown: (options: { label?: string; items: { label: string; value: any }[] }): FilterControl => ({ type: 'dropdown', ...options }),
+    multiselect: (options: { label?: string; items: { label: string; value: any }[], filterable?: boolean }): FilterControl => ({ type: 'multiselect', ...options }),
+    customOperator: (options: { label?: string; operators: { label: string; value: string }[]; valueControl: FilterControl }): FilterControl => ({ type: 'customOperator', ...options }),
+    custom: (component: React.ComponentType<any>, options?: { label?: string; props?: Record<string, any> }): FilterControl => ({ type: 'custom', component, ...options }),
+};
+
+// Helper functions for building FilterExpr values
+export const filterExpr = {
+    equals: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'equals', field, value, ...(transform && { transform }) }),
+    notEquals: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'notEquals', field, value, ...(transform && { transform }) }),
+    greaterThan: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'greaterThan', field, value, ...(transform && { transform }) }),
+    lessThan: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'lessThan', field, value, ...(transform && { transform }) }),
+    greaterThanOrEqual: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'greaterThanOrEqual', field, value, ...(transform && { transform }) }),
+    lessThanOrEqual: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'lessThanOrEqual', field, value, ...(transform && { transform }) }),
+    in: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'in', field, value, ...(transform && { transform }) }),
+    notIn: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'notIn', field, value, ...(transform && { transform }) }),
+    like: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'like', field, value, ...(transform && { transform }) }),
+    iLike: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'iLike', field, value, ...(transform && { transform }) }),
+    isNull: (field: FilterField, value: FilterControl, transform?: FilterTransform): FilterExpr => ({ type: 'isNull', field, value, ...(transform && { transform }) }),
+    and: (filters: FilterExpr[]): FilterExpr => ({ type: 'and', filters }),
+    or: (filters: FilterExpr[]): FilterExpr => ({ type: 'or', filters }),
+    not: (filter: FilterExpr): FilterExpr => ({ type: 'not', filter }),
+    range: (field: FilterField, control: (options: any) => FilterControl, transform?: FilterTransform): FilterExpr =>
+        filterExpr.and([
+            filterExpr.greaterThanOrEqual(field, control({ placeholder: 'from' }), transform),
+            filterExpr.lessThanOrEqual(field, control({ placeholder: 'to' }), transform)
+        ]),
+    allOperators: SUPPORTED_OPERATORS,
+};
+
+// Helper to check if a FilterExpr is a leaf node
+export function isLeaf(expr: FilterExpr): expr is Extract<FilterExpr, { field: FilterField; value: FilterControl }> {
+    return 'field' in expr && 'value' in expr;
+}
+
+// Recursively transform the value of every leaf node in a FilterExpr tree
+export function transformFilterExprValues(expr: FilterExpr, fn: (value: FilterControl) => FilterControl): FilterExpr {
+    if (expr.type === 'and' || expr.type === 'or') {
+        return { ...expr, filters: expr.filters.map(e => transformFilterExprValues(e, fn)) };
+    } else if (expr.type === 'not') {
+        return { ...expr, filter: transformFilterExprValues(expr.filter, fn) };
+    } else {
+        return { ...expr, value: fn(expr.value) };
+    }
+}
+
+export type FilterExprFieldNode = Extract<FilterExpr, { field: FilterField; value: FilterControl }>;
+export type FilterExprFilterListNode = Extract<FilterExpr, { filters: FilterExpr[] }>;
+export type FilterExprNotNode = Extract<FilterExpr, { filter: FilterExpr }>;
+
+// Recursively get all field nodes from a FilterExpr tree
+export function getFieldNodes(expr: FilterExpr): FilterExprFieldNode[] {
+    const nodes: FilterExprFieldNode[] = [];
+    if (isLeaf(expr)) {
+        nodes.push(expr);
+    } else if (expr.type === 'and' || expr.type === 'or') {
+        for (const filter of expr.filters) {
+            nodes.push(...getFieldNodes(filter));
+        }
+    } else if (expr.type === 'not') {
+        nodes.push(...getFieldNodes(expr.filter));
+    }
+    return nodes;
+}
+
+
+
+export type FilterFieldGroup = {
+    name: string;
+    label: string | null;
+};
+
+export type FilterSchema = {
+    id: string; // unique identifier for the filter
+    label: string;
+    expression: FilterExpr;
+    group: string; // group name
+    aiGenerated: boolean;
+};
+
+export type FilterId = FilterSchema['id'];
+
+export type FilterSchemasAndGroups = {
+    groups: FilterFieldGroup[];
+    filters: FilterSchema[];
+};
+
+/**
+ * Attempts to deserialize a plain JSON object into a FilterExpr.
+ * Does not support custom filters or transformation functions.
+ */
+export function filterExprFromJSON(json: any): FilterExpr | null {
+    if (!json || typeof json !== 'object' || !json.type) return null;
+    switch (json.type) {
+        case 'equals':
+        case 'notEquals':
+        case 'greaterThan':
+        case 'lessThan':
+        case 'greaterThanOrEqual':
+        case 'lessThanOrEqual':
+        case 'in':
+        case 'notIn':
+        case 'like':
+        case 'iLike':
+        case 'isNull': {
+            // Only support basic FilterControl types (text, number, date, dropdown, multiselect)
+            if (!json.field || !json.value || typeof json.value !== 'object' || !json.value.type) return null;
+            const allowedTypes = ['text', 'number', 'date', 'dropdown', 'multiselect'];
+            if (!allowedTypes.includes(json.value.type)) return null;
+            return {
+                type: json.type,
+                field: json.field,
+                value: json.value
+            } as FilterExpr;
+        }
+        case 'and':
+        case 'or': {
+            if (!Array.isArray(json.filters)) return null;
+            const children = json.filters.map(filterExprFromJSON).filter(Boolean) as FilterExpr[];
+            return { type: json.type, filters: children };
+        }
+        case 'not': {
+            if (!json.filter) return null;
+            const child = filterExprFromJSON(json.filter);
+            if (!child) return null;
+            return { type: 'not', filter: child };
+        }
+        default:
+            return null;
+    }
+}