@firecms/core 3.3.0 → 3.4.0-canary.63041d0

package/src/components/SelectableTable/filters/filter_text_input.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from "@jest/globals";
+import { filterValueToText, parseFilterTextInput } from "./filter_text_input";
+
+/**
+ * Type `text` one character at a time, the way the filter field does, and keep track
+ * of the filter value left after every keystroke.
+ */
+function typeCharByChar(text: string, dataType: "string" | "number" = "number") {
+    let value: string | number | undefined;
+    const valueAfterEachKeystroke: (string | number | undefined)[] = [];
+    for (let i = 1; i <= text.length; i++) {
+        const result = parseFilterTextInput(text.slice(0, i), dataType);
+        if (result.updateValue)
+            value = result.value;
+        valueAfterEachKeystroke.push(value);
+    }
+    return {
+        value,
+        valueAfterEachKeystroke
+    };
+}
+
+describe("parseFilterTextInput with numbers", () => {
+
+    it("should parse complete numbers", () => {
+        expect(parseFilterTextInput("0.01", "number")).toEqual({
+            updateValue: true,
+            value: 0.01
+        });
+        expect(parseFilterTextInput("1", "number")).toEqual({
+            updateValue: true,
+            value: 1
+        });
+        expect(parseFilterTextInput("1.5", "number")).toEqual({
+            updateValue: true,
+            value: 1.5
+        });
+        expect(parseFilterTextInput("-0.5", "number")).toEqual({
+            updateValue: true,
+            value: -0.5
+        });
+        expect(parseFilterTextInput(".5", "number")).toEqual({
+            updateValue: true,
+            value: 0.5
+        });
+        expect(parseFilterTextInput("1e5", "number")).toEqual({
+            updateValue: true,
+            value: 100000
+        });
+        expect(parseFilterTextInput("0.0100", "number")).toEqual({
+            updateValue: true,
+            value: 0.01
+        });
+    });
+
+    it("should keep 0 as a valid filter value", () => {
+        expect(parseFilterTextInput("0", "number")).toEqual({
+            updateValue: true,
+            value: 0
+        });
+        expect(parseFilterTextInput("0.0", "number")).toEqual({
+            updateValue: true,
+            value: 0
+        });
+        expect(parseFilterTextInput("00", "number")).toEqual({
+            updateValue: true,
+            value: 0
+        });
+        expect(parseFilterTextInput("-0", "number").updateValue).toBe(true);
+    });
+
+    it("should clear the filter for an empty input", () => {
+        expect(parseFilterTextInput("", "number")).toEqual({
+            updateValue: true,
+            value: undefined
+        });
+        expect(parseFilterTextInput("   ", "number")).toEqual({
+            updateValue: true,
+            value: undefined
+        });
+    });
+
+    it("should not touch the filter value for intermediate inputs", () => {
+        // these are states the user goes through while typing, the text must be kept
+        // in the input without the filter value being changed
+        expect(parseFilterTextInput("0.", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput(".", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("1.", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("-", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("-.", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("+", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("-0.", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("1e", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("1e-", "number")).toEqual({ updateValue: false });
+    });
+
+    it("should not touch the filter value for text that is not a number", () => {
+        expect(parseFilterTextInput("abc", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("12abc", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("1.2.3", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("--1", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("0x10", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("Infinity", "number")).toEqual({ updateValue: false });
+        expect(parseFilterTextInput("1e999", "number")).toEqual({ updateValue: false });
+    });
+
+    it("should allow typing 0.01 character by character", () => {
+        const { value, valueAfterEachKeystroke } = typeCharByChar("0.01");
+        expect(value).toBe(0.01);
+        // "0" -> 0, "0." -> unchanged, "0.0" -> 0, "0.01" -> 0.01
+        expect(valueAfterEachKeystroke).toEqual([0, 0, 0, 0.01]);
+    });
+
+    it("should allow typing other decimals character by character", () => {
+        expect(typeCharByChar("0.001").value).toBe(0.001);
+        expect(typeCharByChar("-0.5").value).toBe(-0.5);
+        expect(typeCharByChar(".5").value).toBe(0.5);
+        expect(typeCharByChar(".01").value).toBe(0.01);
+        expect(typeCharByChar("1.05").value).toBe(1.05);
+        expect(typeCharByChar("10.00001").value).toBe(10.00001);
+        expect(typeCharByChar("-.5").value).toBe(-0.5);
+    });
+
+    it("should keep the previous value while typing a trailing decimal separator", () => {
+        // typing "1." leaves the value at 1, the text "1." stays in the input
+        expect(typeCharByChar("1.").value).toBe(1);
+        expect(typeCharByChar("1.").valueAfterEachKeystroke).toEqual([1, 1]);
+    });
+
+    it("should not commit a value until a leading sign is followed by digits", () => {
+        expect(typeCharByChar("-").value).toBeUndefined();
+        expect(typeCharByChar("-1").valueAfterEachKeystroke).toEqual([undefined, -1]);
+    });
+
+    it("should clear the value when the input is emptied", () => {
+        // deleting "0.01" one character at a time, from the end
+        const texts = ["0.0", "0.", "0", ""];
+        let value: string | number | undefined = 0.01;
+        for (const text of texts) {
+            const result = parseFilterTextInput(text, "number");
+            if (result.updateValue)
+                value = result.value;
+        }
+        expect(value).toBeUndefined();
+    });
+});
+
+describe("parseFilterTextInput with strings", () => {
+
+    it("should use the text as the value", () => {
+        expect(parseFilterTextInput("abc", "string")).toEqual({
+            updateValue: true,
+            value: "abc"
+        });
+        expect(parseFilterTextInput("0.", "string")).toEqual({
+            updateValue: true,
+            value: "0."
+        });
+        expect(parseFilterTextInput("", "string")).toEqual({
+            updateValue: true,
+            value: ""
+        });
+        expect(parseFilterTextInput("  spaced  ", "string")).toEqual({
+            updateValue: true,
+            value: "  spaced  "
+        });
+    });
+});
+
+describe("filterValueToText", () => {
+
+    it("should render values as text", () => {
+        expect(filterValueToText(0)).toBe("0");
+        expect(filterValueToText(0.01)).toBe("0.01");
+        expect(filterValueToText(-0.5)).toBe("-0.5");
+        expect(filterValueToText("abc")).toBe("abc");
+        expect(filterValueToText("")).toBe("");
+    });
+
+    it("should render empty text for no value", () => {
+        expect(filterValueToText(undefined)).toBe("");
+        expect(filterValueToText(null)).toBe("");
+    });
+});

package/src/components/SelectableTable/filters/filter_text_input.ts

@@ -0,0 +1,71 @@
+/**
+ * Matches text that is a complete number, as opposed to an intermediate state
+ * that the user may be in the middle of typing, like "-", "0." or ".".
+ * A decimal separator must be followed by at least one digit.
+ */
+const completeNumberRegex = /^[+-]?(?:\d+|\d*\.\d+)(?:[eE][+-]?\d+)?$/;
+
+export type FilterTextInputParseResult = {
+    /**
+     * Whether the filter value should be updated with `value`.
+     * It is `false` for intermediate inputs that are not a valid value yet,
+     * like "-" or "0.", so that the text typed by the user can be kept as it is
+     * while the current filter value is left untouched.
+     */
+    updateValue: boolean;
+
+    /**
+     * Parsed value, only relevant when `updateValue` is `true`.
+     * `undefined` means the filter should be cleared.
+     */
+    value?: string | number;
+};
+
+/**
+ * Turn the raw text of a filter input into the value used by the filter.
+ *
+ * The text shown to the user is never derived back from the parsed value, so
+ * intermediate states like "0.", ".0" or "-" survive while typing. Numbers are
+ * only committed to the filter once the text is a complete number, which makes
+ * values such as 0.01 reachable by typing them character by character.
+ *
+ * Note that `0` is a perfectly valid filter value, only an empty input clears
+ * the filter.
+ */
+export function parseFilterTextInput(text: string, dataType: "string" | "number"): FilterTextInputParseResult {
+
+    if (dataType !== "number")
+        return {
+            updateValue: true,
+            value: text
+        };
+
+    const trimmedText = text.trim();
+
+    if (trimmedText === "")
+        return {
+            updateValue: true,
+            value: undefined
+        };
+
+    if (!completeNumberRegex.test(trimmedText))
+        return { updateValue: false };
+
+    const parsedValue = Number(trimmedText);
+    if (!isFinite(parsedValue))
+        return { updateValue: false };
+
+    return {
+        updateValue: true,
+        value: parsedValue
+    };
+}
+
+/**
+ * Text a filter input should display for a given filter value.
+ */
+export function filterValueToText(value: unknown): string {
+    if (value === undefined || value === null)
+        return "";
+    return String(value);
+}

package/src/components/VirtualTable/VirtualTable.tsx

@@ -135,7 +135,7 @@ export const VirtualTable = React.memo<VirtualTableProps<any>>(
         const [columns, setColumns] = useState(columnsProp);
 
         const tableRef = useRef<HTMLDivElement>(null);
-        const endReachCallbackThreshold = useRef<number>(0);
+        const lastEndReachedDataLength = useRef<number | undefined>(undefined);
 
         const debouncedScroll = useDebounceCallback(onScrollProp, 200);
 
@@ -242,7 +242,7 @@ export const VirtualTable = React.memo<VirtualTableProps<any>>(
         }, [filterInput]);
 
         const scrollToTop = useCallback(() => {
-            endReachCallbackThreshold.current = 0;
+            lastEndReachedDataLength.current = undefined;
             if (tableRef.current) {
                 tableRef.current.scrollTo(tableRef.current?.scrollLeft, 0);
             }
@@ -278,13 +278,24 @@ export const VirtualTable = React.memo<VirtualTableProps<any>>(
 
         const maxScroll = Math.max((data?.length ?? 0) * rowHeight - bounds.height, 0);
 
-        const onEndReachedInternal = useCallback((scrollOffset: number) => {
-            if (onEndReached && (data?.length ?? 0) > 0 && scrollOffset > endReachCallbackThreshold.current + endOffset) {
-                endReachCallbackThreshold.current = scrollOffset;
+        const onEndReachedInternal = useCallback(() => {
+            const dataLength = data?.length ?? 0;
+
+            if (onEndReached && dataLength > 0 && lastEndReachedDataLength.current !== dataLength) {
+                lastEndReachedDataLength.current = dataLength;
                 onEndReached();
             }
         }, [data?.length, onEndReached]);
 
+        useEffect(() => {
+            if (!onEndReached || loading || !data?.length || !bounds.height || !tableRef.current) {
+                return;
+            }
+            if (tableRef.current.scrollHeight <= tableRef.current.clientHeight) {
+                onEndReachedInternal();
+            }
+        }, [bounds.height, data?.length, loading, onEndReached, onEndReachedInternal]);
+
         const onScroll = useCallback(({
             scrollDirection,
             scrollOffset,
@@ -302,12 +313,12 @@ export const VirtualTable = React.memo<VirtualTableProps<any>>(
                 })
             }
             if (!scrollUpdateWasRequested && (scrollOffset >= maxScroll - endOffset))
-                onEndReachedInternal(scrollOffset);
-        }, [maxScroll, onEndReachedInternal]);
+                onEndReachedInternal();
+        }, [endOffset, maxScroll, onEndReachedInternal]);
 
         const onFilterUpdateInternal = useCallback((column: VirtualTableColumn, filterForProperty?: [VirtualTableWhereFilterOp, any]) => {
 
-            endReachCallbackThreshold.current = 0;
+            lastEndReachedDataLength.current = undefined;
             const filter = filterRef.current;
             let newFilterValue: VirtualTableFilterValues<any> = filter ? { ...filter } : {};
 

package/src/components/common/table_url_params.ts

@@ -0,0 +1,172 @@
+import { EntityReference, FilterValues, WhereFilterOp } from "../../types";
+import { decodeEntityId, encodeEntityId } from "../../util/navigation_utils";
+
+/**
+ * Internal helpers used by `useDataSourceTableController` to persist the state of a
+ * collection table (filters, sort and text search) in the URL query string.
+ *
+ * These functions are intentionally NOT re-exported by the package barrel files:
+ * they are pure and live in their own module only so that they can be unit tested.
+ * `encodeFilterAndSort` and `parseFilterAndSort` must stay exact inverses of each
+ * other, otherwise state written to the URL is silently dropped on reload.
+ */
+
+/**
+ * Serialise the state of a collection table into a URL query string,
+ * without the leading `?`. Returns an empty string when there is no state to persist.
+ */
+export function encodeFilterAndSort(filterValues?: FilterValues<string>,
+                                    sortBy?: [string, "asc" | "desc"] | undefined,
+                                    searchString?: string) {
+    const entries: Record<string, string> = {};
+    if (sortBy) {
+        entries["__sort"] = encodeURIComponent(sortBy[0]);
+        entries["__sort_order"] = encodeURIComponent(sortBy[1]);
+    }
+    if (filterValues) {
+        Object.entries(filterValues).forEach(([key, value]) => {
+            if (value) {
+                const [op, val] = value;
+                let encodedValue: any = val;
+                try {
+                    if (typeof val === "object") {
+                        if (val instanceof Date) {
+                            encodedValue = val.toISOString();
+                        } else if (Array.isArray(val)) {
+                            encodedValue = JSON.stringify(val, (key, value) => {
+                                if (value instanceof EntityReference) {
+                                    return encodeRef(value);
+                                }
+                                return value;
+                            });
+                        } else if (val instanceof EntityReference) {
+                            encodedValue = encodeRef(val);
+                        }
+                    } else if (typeof val === "string") {
+                        // JSON.stringify wraps the string in quotes (e.g. "4" → '"4"')
+                        // so that decodeString's JSON.parse restores the string type,
+                        // not a number. Without this, "4" round-trips as the number 4.
+                        encodedValue = JSON.stringify(val);
+                    }
+                } catch (e) {
+                    encodedValue = val;
+                }
+                if (encodedValue !== undefined) {
+                    entries[encodeURIComponent(`${key}_op`)] = encodeURIComponent(op);
+                    // Note: check for null/undefined explicitly instead of truthiness,
+                    // otherwise falsy-but-valid values (boolean `false`, number `0`)
+                    // would be serialized as "null" and round-trip back as `null`,
+                    // breaking filters like `archived == false`.
+                    entries[encodeURIComponent(`${key}_value`)] = encodedValue !== null && encodedValue !== undefined
+                        ? encodeURIComponent(encodedValue.toString())
+                        : "null";
+                }
+            }
+        });
+    }
+    // The text search term is encoded once here; `parseFilterAndSort` reads it back with
+    // `URLSearchParams`, which decodes exactly once. Do NOT decode it a second time or
+    // terms containing a literal `%` (e.g. "50%") would throw a URIError.
+    if (searchString) {
+        entries["search"] = encodeURIComponent(searchString);
+    }
+    if (!Object.keys(entries).length) {
+        return "";
+    }
+    return Object.entries(entries).map(([key, value]) => `${key}=${value}`).join("&");
+}
+
+/**
+ * Restore the state of a collection table from a URL query string.
+ * The inverse of {@link encodeFilterAndSort}.
+ */
+export function parseFilterAndSort<M>(search: string): {
+    filterValues: FilterValues<string> | undefined,
+    sortBy?: [Extract<keyof M, string>, "asc" | "desc"],
+    searchString?: string
+} {
+    const entries = new URLSearchParams(search);
+    const filterValues: FilterValues<string> = {};
+    let sortBy: [string, "asc" | "desc"] | undefined = undefined;
+    entries.forEach((value, key) => {
+        if (key === "__sort") {
+            sortBy = [decodeURIComponent(value), entries.get("__sort_order") as "asc" | "desc"];
+        } else if (key.endsWith("_op")) {
+            const field = key.replace("_op", "");
+            const filterOp = decodeURIComponent(value) as WhereFilterOp;
+            const filterValStr = entries.get(`${field}_value`);
+            if (filterValStr !== null) {
+                filterValues[field] = [filterOp, decodeString(filterValStr)];
+            }
+        }
+    });
+
+    // `URLSearchParams` has already percent-decoded the value, so it is used as is.
+    const searchString = entries.get("search") ?? undefined;
+
+    return {
+        filterValues: Object.keys(filterValues).length ? filterValues : undefined,
+        sortBy,
+        searchString: searchString ? searchString : undefined
+    }
+}
+
+function isDate(dateString: string): boolean {
+    // Define a regex pattern that matches the exact date format: 2025-01-07T23:00:00.000Z
+    const regexPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+    // Test the dateString against the regex pattern
+    if (!regexPattern.test(dateString)) {
+        return false;
+    }
+
+    // If the regex matches, further validate if it is a valid UTC date
+    const date = new Date(dateString);
+    return date.toISOString() === dateString;
+}
+
+function encodeRef(val: EntityReference) {
+    return `ref::${val.path}/${encodeEntityId(val.id)}`;
+}
+
+/**
+ * Split a "path/id" reference on its LAST separator: the path may itself be a
+ * subcollection path with several segments, and the id is escaped so it is always exactly
+ * one segment.
+ */
+function decodeRef(encoded: string): EntityReference {
+    const separatorIndex = encoded.lastIndexOf("/");
+    if (separatorIndex < 0) return new EntityReference(encoded, "");
+    return new EntityReference(
+        decodeEntityId(encoded.substring(separatorIndex + 1)),
+        encoded.substring(0, separatorIndex)
+    );
+}
+
+function decodeString(val: string): EntityReference | Date | string {
+    let parsedFilterVal: any = val;
+    if (isDate(val)) {
+        try {
+            parsedFilterVal = new Date(val);
+        } catch (e) {
+            // ignore
+        }
+    }
+    if (typeof parsedFilterVal === "string") {
+        try {
+            parsedFilterVal = JSON.parse(parsedFilterVal, (key, value) => {
+                if (typeof value === "string" && value.startsWith("ref::")) {
+                    return decodeRef(value.substring(5));
+                }
+                return value;
+            });
+        } catch (e) {
+            // ignore
+        }
+    }
+
+    if (typeof parsedFilterVal === "string" && parsedFilterVal.startsWith("ref::")) {
+        return decodeRef(parsedFilterVal.substring(5));
+    }
+    return parsedFilterVal;
+}