@olenbetong/appframe-core 2.11.9 → 2.12.0

package/es/filter/operators.test.js

@@ -0,0 +1,106 @@
+import { describe, expect, test } from "vitest";
+import { getDefaultOperator, getDynamicValuesForField, getOperatorArity, getOperatorLabel, getOperatorsForField, getValueType, normalizeOperator, } from "./operators.js";
+describe("getOperatorsForField", () => {
+    test("boolean fields only get truth checks", () => {
+        expect(getOperatorsForField({ type: "boolean" })).toEqual(["istrue", "isfalse"]);
+    });
+    test("boolean fields never get null checks", () => {
+        expect(getOperatorsForField({ type: "boolean", nullable: true })).toEqual(["istrue", "isfalse"]);
+    });
+    test("nullable fields get null checks last", () => {
+        let operators = getOperatorsForField({ type: "number", nullable: true });
+        expect(operators.slice(-2)).toEqual(["isnull", "isnotnull"]);
+    });
+    test("string fields get the string comparison operators", () => {
+        let operators = getOperatorsForField({ type: "string" });
+        expect(operators).toContain("contains");
+        expect(operators).toContain("beginswith");
+        expect(operators).toContain("isblank");
+    });
+    test("number fields do not get string comparison operators", () => {
+        let operators = getOperatorsForField({ type: "number" });
+        expect(operators).not.toContain("contains");
+        expect(operators).not.toContain("beginswith");
+    });
+    test("unknown field types fall back to the string operators", () => {
+        let operators = getOperatorsForField({ type: "something" });
+        expect(operators).toEqual(getOperatorsForField({ type: "string" }));
+    });
+});
+describe("getDefaultOperator", () => {
+    test.each([
+        ["string", "beginswith"],
+        ["number", "equals"],
+        ["date", "equals"],
+        ["datetime", "equals"],
+        ["boolean", "istrue"],
+    ])("%s defaults to %s", (type, expected) => {
+        expect(getDefaultOperator({ type })).toBe(expected);
+    });
+});
+describe("getOperatorArity", () => {
+    test.each([
+        ["isnull", "none"],
+        ["istrue", "none"],
+        ["isblank", "none"],
+        ["between", "pair"],
+        ["datenotbetween", "pair"],
+        ["inlist", "list"],
+        ["notinlist", "list"],
+        ["equals", "single"],
+        ["contains", "single"],
+    ])("%s has arity %s", (operator, expected) => {
+        expect(getOperatorArity(operator)).toBe(expected);
+    });
+});
+describe("getOperatorLabel", () => {
+    test("date fields get the relative wording for comparisons", () => {
+        expect(getOperatorLabel("greaterthan", "date")).toBe("After");
+        expect(getOperatorLabel("lessthanorequal", "datetime")).toBe("Up to");
+    });
+    test("number fields get the numeric wording", () => {
+        expect(getOperatorLabel("greaterthan", "number")).toBe("Greater than");
+    });
+    test("non-comparison operators are unaffected by the field type", () => {
+        expect(getOperatorLabel("inlist", "date")).toBe("In list");
+        expect(getOperatorLabel("inlist", "number")).toBe("In list");
+    });
+});
+describe("getValueType", () => {
+    test("parameterless operators send a null value type", () => {
+        expect(getValueType({ type: "string" }, "isnull")).toBe("null");
+        expect(getValueType({ type: "boolean" }, "istrue")).toBe("null");
+    });
+    test.each([
+        ["string", "string"],
+        ["number", "number"],
+        ["date", "datetime"],
+        ["datetime", "datetime"],
+        ["uniqueidentifier", "uniqueidentifier"],
+    ])("%s fields send %s", (type, expected) => {
+        expect(getValueType({ type }, "equals")).toBe(expected);
+    });
+});
+describe("normalizeOperator", () => {
+    test.each([
+        ["Equals", "equals"],
+        ["BeginsWith", "beginswith"],
+        ["NotDateEquals", "notdatequals"],
+        ["Not", "notequals"],
+        ["Tweens", "notbetween"],
+        ["Not, Date", "notdatequals"],
+    ])("%s normalizes to %s", (input, expected) => {
+        expect(normalizeOperator(input)).toBe(expected);
+    });
+});
+describe("getDynamicValuesForField", () => {
+    test("date fields get relative dates", () => {
+        expect(getDynamicValuesForField({ type: "date" })).toContain("ThisMonth");
+    });
+    test("string fields only get the current user", () => {
+        expect(getDynamicValuesForField({ type: "string" })).toEqual(["CurrentUser"]);
+    });
+    test("number fields get none", () => {
+        expect(getDynamicValuesForField({ type: "number" })).toEqual([]);
+    });
+});

package/es/filter/savedFilters.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Saved filters — the filters the Windows filter builder stores in
+ * `stbl_Database_Filters` and shares between users through
+ * `stbl_Database_FiltersPermissions`.
+ *
+ * This module is the pure part: the shape of a saved filter, how the raw
+ * database records map onto it, and who is allowed to do what with one. The
+ * loading and the mutations live in `useSavedFilters` in
+ * `@olenbetong/appframe-react`.
+ */
+import type { FilterAccessLevel } from "./types.js";
+/**
+ * Access a user has to a saved filter.
+ *
+ * `sviw_Database_MyFilters` only ever reports `Reader`, `Editor` or `Manager`,
+ * and a filter the current user created is always reported as `Manager`.
+ */
+export type { FilterAccessLevel };
+/**
+ * `sviw_Database_MyFilters` unions in a synthetic "No Filter" row so the Windows
+ * tree can render a "no filter" entry. It is not a real filter and must be
+ * dropped before the list is shown.
+ */
+export declare const NO_FILTER_ID = -1;
+/** A saved filter, as used by the filter builder UI. */
+export type SavedFilter = {
+    filterId: number;
+    primKey: string;
+    name: string;
+    /** DevExpress criteria string, e.g. `[Name] Like '%a%'`. */
+    criteria: string;
+    dbObjectId: string;
+    accessLevel: FilterAccessLevel;
+    /** True when the current user created the filter. */
+    createdByUser: boolean;
+    createdBy: string;
+    domain: string | null;
+    /** True when the filter is visible in every domain the user has access to. */
+    crossDomain: boolean;
+    /** True when the filter is shared with individual users rather than groups. */
+    isPersonallyShared: boolean;
+    /** True when the criteria are hidden from readers of a shared filter. */
+    hideCriteria: boolean;
+    headerText: string | null;
+    comment: string | null;
+    /** Report parameter values, stored as XML. Only used by report filters. */
+    parameters: string | null;
+    reportTitle: string | null;
+    created: Date | null;
+    updated: Date | null;
+};
+/** A raw `sviw_Database_MyFilters` / `sviw_Database_FiltersFromReportID` record. */
+export type SavedFilterRecord = {
+    PrimKey?: string | null;
+    FilterID?: number | null;
+    DBObjectID?: string | null;
+    FilterName?: string | null;
+    FilterCriteria?: string | null;
+    AccessLevel?: string | null;
+    CreatedByUser?: string | boolean | null;
+    CreatedBy?: string | null;
+    Domain?: string | null;
+    CrossDomain?: boolean | number | null;
+    IsPersonallyShared?: boolean | number | null;
+    HideFilterCriteria?: boolean | number | null;
+    OptionalHeaderText?: string | null;
+    OptionalComment?: string | null;
+    Parameters?: string | null;
+    ReportTitle?: string | null;
+    Created?: Date | string | null;
+    Updated?: Date | string | null;
+};
+/**
+ * Maps a database record onto a `SavedFilter`.
+ *
+ * `CreatedByUser` needs care: the view computes it as the *string* `'true'` or
+ * `'false'` (and `'False'` on the synthetic row), not as a bit.
+ */
+export declare function toSavedFilter(record: SavedFilterRecord): SavedFilter;
+/** Drops the synthetic "No Filter" row and sorts by name. */
+export declare function toSavedFilters(records: SavedFilterRecord[]): SavedFilter[];
+/**
+ * Splits filters into the two branches the Windows tree shows: the ones the user
+ * created, and the ones that have been shared with them.
+ */
+export declare function partitionSavedFilters(filters: SavedFilter[]): {
+    mine: SavedFilter[];
+    shared: SavedFilter[];
+};
+export declare function findSavedFilter(filters: SavedFilter[], filterId: number | null | undefined): SavedFilter | undefined;
+/** True when the user may overwrite the filter's criteria. */
+export declare function canEditSavedFilter(filter: SavedFilter): boolean;
+/** True when the user may change who the filter is shared with. */
+export declare function canShareSavedFilter(filter: SavedFilter): boolean;
+/**
+ * True when the user may rename or delete the filter.
+ *
+ * `sstp_WebSiteCMS_FilterBuilder_RenameFilter` and `…_DeleteFilter` both require
+ * `CreatedBy = SUSER_SNAME()` — the manager-access branch is commented out in
+ * both procedures, deliberately, because the UI only ever offers these for a
+ * user's own filters.
+ */
+export declare function canRenameSavedFilter(filter: SavedFilter): boolean;
+export declare const canDeleteSavedFilter: typeof canRenameSavedFilter;
+/**
+ * True when the user may toggle the cross-domain flag.
+ *
+ * `sstp_Database_Filters_SetCrossDomain` also filters on
+ * `CreatedBy = SUSER_SNAME()`.
+ */
+export declare const canSetCrossDomain: typeof canRenameSavedFilter;

package/es/filter/savedFilters.js

@@ -0,0 +1,118 @@
+/**
+ * Saved filters — the filters the Windows filter builder stores in
+ * `stbl_Database_Filters` and shares between users through
+ * `stbl_Database_FiltersPermissions`.
+ *
+ * This module is the pure part: the shape of a saved filter, how the raw
+ * database records map onto it, and who is allowed to do what with one. The
+ * loading and the mutations live in `useSavedFilters` in
+ * `@olenbetong/appframe-react`.
+ */
+/**
+ * `sviw_Database_MyFilters` unions in a synthetic "No Filter" row so the Windows
+ * tree can render a "no filter" entry. It is not a real filter and must be
+ * dropped before the list is shown.
+ */
+export const NO_FILTER_ID = -1;
+/**
+ * Maps a database record onto a `SavedFilter`.
+ *
+ * `CreatedByUser` needs care: the view computes it as the *string* `'true'` or
+ * `'false'` (and `'False'` on the synthetic row), not as a bit.
+ */
+export function toSavedFilter(record) {
+    return {
+        filterId: record.FilterID ?? NO_FILTER_ID,
+        primKey: record.PrimKey ?? "",
+        name: record.FilterName ?? "",
+        criteria: record.FilterCriteria ?? "",
+        dbObjectId: record.DBObjectID ?? "",
+        accessLevel: toAccessLevel(record.AccessLevel),
+        createdByUser: toBoolean(record.CreatedByUser),
+        createdBy: record.CreatedBy ?? "",
+        domain: record.Domain ?? null,
+        crossDomain: toBoolean(record.CrossDomain),
+        isPersonallyShared: toBoolean(record.IsPersonallyShared),
+        hideCriteria: toBoolean(record.HideFilterCriteria),
+        headerText: record.OptionalHeaderText || null,
+        comment: record.OptionalComment || null,
+        parameters: record.Parameters || null,
+        reportTitle: record.ReportTitle || null,
+        created: toDate(record.Created),
+        updated: toDate(record.Updated),
+    };
+}
+function toAccessLevel(value) {
+    if (value === "Manager" || value === "Editor")
+        return value;
+    return "Reader";
+}
+function toBoolean(value) {
+    if (typeof value === "string")
+        return value.toLowerCase() === "true";
+    return Boolean(value);
+}
+function toDate(value) {
+    if (!value)
+        return null;
+    if (value instanceof Date)
+        return value;
+    let date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/** Drops the synthetic "No Filter" row and sorts by name. */
+export function toSavedFilters(records) {
+    return records
+        .filter((record) => (record.FilterID ?? NO_FILTER_ID) !== NO_FILTER_ID)
+        .map(toSavedFilter)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Splits filters into the two branches the Windows tree shows: the ones the user
+ * created, and the ones that have been shared with them.
+ */
+export function partitionSavedFilters(filters) {
+    let mine = [];
+    let shared = [];
+    for (let filter of filters) {
+        if (filter.createdByUser) {
+            mine.push(filter);
+        }
+        else {
+            shared.push(filter);
+        }
+    }
+    return { mine, shared };
+}
+export function findSavedFilter(filters, filterId) {
+    if (filterId == null)
+        return undefined;
+    return filters.find((filter) => filter.filterId === filterId);
+}
+/** True when the user may overwrite the filter's criteria. */
+export function canEditSavedFilter(filter) {
+    return filter.accessLevel === "Editor" || filter.accessLevel === "Manager";
+}
+/** True when the user may change who the filter is shared with. */
+export function canShareSavedFilter(filter) {
+    return filter.accessLevel === "Manager";
+}
+/**
+ * True when the user may rename or delete the filter.
+ *
+ * `sstp_WebSiteCMS_FilterBuilder_RenameFilter` and `…_DeleteFilter` both require
+ * `CreatedBy = SUSER_SNAME()` — the manager-access branch is commented out in
+ * both procedures, deliberately, because the UI only ever offers these for a
+ * user's own filters.
+ */
+export function canRenameSavedFilter(filter) {
+    return filter.createdByUser;
+}
+export const canDeleteSavedFilter = canRenameSavedFilter;
+/**
+ * True when the user may toggle the cross-domain flag.
+ *
+ * `sstp_Database_Filters_SetCrossDomain` also filters on
+ * `CreatedBy = SUSER_SNAME()`.
+ */
+export const canSetCrossDomain = canRenameSavedFilter;

package/es/filter/savedFilters.test.d.ts

@@ -0,0 +1 @@
+export {};

package/es/filter/savedFilters.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "vitest";
+import { canDeleteSavedFilter, canEditSavedFilter, canRenameSavedFilter, canShareSavedFilter, findSavedFilter, NO_FILTER_ID, partitionSavedFilters, toSavedFilter, toSavedFilters, } from "./savedFilters.js";
+function record(overrides = {}) {
+    return {
+        PrimKey: "11111111-1111-1111-1111-111111111111",
+        FilterID: 1,
+        DBObjectID: "aviw_Test_View",
+        FilterName: "My filter",
+        FilterCriteria: "[Name] = 'a'",
+        AccessLevel: "Manager",
+        CreatedByUser: "true",
+        CreatedBy: "bvh",
+        Domain: "OB",
+        CrossDomain: false,
+        IsPersonallyShared: 0,
+        HideFilterCriteria: 0,
+        ...overrides,
+    };
+}
+describe("toSavedFilter", () => {
+    test("maps a record", () => {
+        let filter = toSavedFilter(record());
+        expect(filter).toMatchObject({
+            filterId: 1,
+            name: "My filter",
+            criteria: "[Name] = 'a'",
+            dbObjectId: "aviw_Test_View",
+            accessLevel: "Manager",
+            createdByUser: true,
+            crossDomain: false,
+        });
+    });
+    test("CreatedByUser is a string, not a bit", () => {
+        expect(toSavedFilter(record({ CreatedByUser: "false" })).createdByUser).toBe(false);
+        expect(toSavedFilter(record({ CreatedByUser: "False" })).createdByUser).toBe(false);
+        expect(toSavedFilter(record({ CreatedByUser: "true" })).createdByUser).toBe(true);
+    });
+    test("bit columns arrive as numbers", () => {
+        let filter = toSavedFilter(record({ CrossDomain: 1, IsPersonallyShared: 1, HideFilterCriteria: 1 }));
+        expect(filter.crossDomain).toBe(true);
+        expect(filter.isPersonallyShared).toBe(true);
+        expect(filter.hideCriteria).toBe(true);
+    });
+    test("an unknown access level falls back to Reader", () => {
+        expect(toSavedFilter(record({ AccessLevel: null })).accessLevel).toBe("Reader");
+    });
+    test("empty optional strings become null", () => {
+        let filter = toSavedFilter(record({ OptionalHeaderText: "", OptionalComment: "" }));
+        expect(filter.headerText).toBeNull();
+        expect(filter.comment).toBeNull();
+    });
+    test("dates are parsed", () => {
+        expect(toSavedFilter(record({ Created: "2026-01-02T03:04:05Z" })).created).toBeInstanceOf(Date);
+        expect(toSavedFilter(record({ Created: null })).created).toBeNull();
+    });
+});
+describe("toSavedFilters", () => {
+    test("drops the synthetic No Filter row", () => {
+        let filters = toSavedFilters([record({ FilterID: NO_FILTER_ID, FilterName: "No Filter" }), record()]);
+        expect(filters).toHaveLength(1);
+        expect(filters[0].name).toBe("My filter");
+    });
+    test("sorts by name", () => {
+        let filters = toSavedFilters([
+            record({ FilterID: 1, FilterName: "Beta" }),
+            record({ FilterID: 2, FilterName: "Alpha" }),
+        ]);
+        expect(filters.map((filter) => filter.name)).toEqual(["Alpha", "Beta"]);
+    });
+});
+describe("partitionSavedFilters", () => {
+    test("splits on createdByUser", () => {
+        let filters = toSavedFilters([
+            record({ FilterID: 1, FilterName: "Mine", CreatedByUser: "true" }),
+            record({ FilterID: 2, FilterName: "Theirs", CreatedByUser: "false" }),
+        ]);
+        let { mine, shared } = partitionSavedFilters(filters);
+        expect(mine.map((filter) => filter.name)).toEqual(["Mine"]);
+        expect(shared.map((filter) => filter.name)).toEqual(["Theirs"]);
+    });
+});
+describe("permissions", () => {
+    test("a reader can neither edit nor share", () => {
+        let filter = toSavedFilter(record({ AccessLevel: "Reader", CreatedByUser: "false" }));
+        expect(canEditSavedFilter(filter)).toBe(false);
+        expect(canShareSavedFilter(filter)).toBe(false);
+    });
+    test("an editor can edit but not share", () => {
+        let filter = toSavedFilter(record({ AccessLevel: "Editor", CreatedByUser: "false" }));
+        expect(canEditSavedFilter(filter)).toBe(true);
+        expect(canShareSavedFilter(filter)).toBe(false);
+    });
+    test("renaming and deleting need ownership, not manager access", () => {
+        let managed = toSavedFilter(record({ AccessLevel: "Manager", CreatedByUser: "false" }));
+        expect(canShareSavedFilter(managed)).toBe(true);
+        expect(canRenameSavedFilter(managed)).toBe(false);
+        expect(canDeleteSavedFilter(managed)).toBe(false);
+        expect(canRenameSavedFilter(toSavedFilter(record()))).toBe(true);
+    });
+});
+describe("findSavedFilter", () => {
+    test("finds by id and tolerates null", () => {
+        let filters = toSavedFilters([record({ FilterID: 7, FilterName: "Seven" })]);
+        expect(findSavedFilter(filters, 7)?.name).toBe("Seven");
+        expect(findSavedFilter(filters, 8)).toBeUndefined();
+        expect(findSavedFilter(filters, null)).toBeUndefined();
+    });
+});

package/es/filter/standardLayout.d.ts

@@ -0,0 +1,18 @@
+import type { FilterExpression, FilterGroup, FilterTree } from "./types.js";
+/**
+ * The "standard layout" is the simplified shape the Windows filter editor can
+ * render in its flow view: an outer `or` group whose items are `and` groups of
+ * expressions. Anything else falls back to the advanced (DevExpress) editor
+ * there, and to the nested tree editor on the web.
+ *
+ * @see `afFilterEditor.CanRenderFilter`
+ */
+export declare function isStandardLayout(filter: FilterGroup | FilterExpression | null | undefined): boolean;
+/**
+ * Coerces an arbitrary filter tree into the standard layout.
+ *
+ * An `or` group's items each become their own `and` group. Anything else is
+ * flattened into a single `and` group. This loses nesting, so only use it when
+ * the consumer cannot handle a nested tree.
+ */
+export declare function coerceToStandardLayout(filter: FilterGroup | FilterExpression | null | undefined): FilterTree;

package/es/filter/standardLayout.js

@@ -0,0 +1,55 @@
+import { isExpression, isGroup } from "./tree.js";
+/**
+ * The "standard layout" is the simplified shape the Windows filter editor can
+ * render in its flow view: an outer `or` group whose items are `and` groups of
+ * expressions. Anything else falls back to the advanced (DevExpress) editor
+ * there, and to the nested tree editor on the web.
+ *
+ * @see `afFilterEditor.CanRenderFilter`
+ */
+export function isStandardLayout(filter) {
+    if (!filter || isExpression(filter) || filter.mode !== "or")
+        return false;
+    return filter.items.every((item) => isGroup(item) && item.mode === "and" && item.items.every(isExpression));
+}
+/**
+ * Coerces an arbitrary filter tree into the standard layout.
+ *
+ * An `or` group's items each become their own `and` group. Anything else is
+ * flattened into a single `and` group. This loses nesting, so only use it when
+ * the consumer cannot handle a nested tree.
+ */
+export function coerceToStandardLayout(filter) {
+    if (!filter)
+        return { type: "group", mode: "or", items: [{ type: "group", mode: "and", items: [] }] };
+    if (isExpression(filter)) {
+        return { type: "group", mode: "or", items: [{ type: "group", mode: "and", items: [filter] }] };
+    }
+    if (filter.mode === "or") {
+        let groups = filter.items.map((item) => {
+            let expressions = [];
+            collectExpressions(item, expressions);
+            return { type: "group", mode: "and", items: expressions };
+        });
+        return {
+            type: "group",
+            mode: "or",
+            items: groups.length > 0 ? groups : [{ type: "group", mode: "and", items: [] }],
+        };
+    }
+    let expressions = [];
+    collectExpressions(filter, expressions);
+    return { type: "group", mode: "or", items: [{ type: "group", mode: "and", items: expressions }] };
+}
+/**
+ * Collects every expression in a (possibly nested) filter, in document order.
+ */
+function collectExpressions(item, into) {
+    if (isExpression(item)) {
+        into.push(item);
+        return;
+    }
+    for (let child of item.items) {
+        collectExpressions(child, into);
+    }
+}

package/es/filter/standardLayout.test.d.ts

@@ -0,0 +1 @@
+export {};

package/es/filter/standardLayout.test.js

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "vitest";
+import { coerceToStandardLayout, isStandardLayout } from "./standardLayout.js";
+import { countExpressions } from "./tree.js";
+function expression(column, operator = "equals", value = "x") {
+    return { type: "expression", column, operator, value, valueType: "string" };
+}
+function group(mode, ...items) {
+    return { type: "group", mode, items };
+}
+describe("isStandardLayout", () => {
+    test("an or of and groups is standard", () => {
+        expect(isStandardLayout(group("or", group("and", expression("A"))))).toBe(true);
+    });
+    test("an and root is not standard", () => {
+        expect(isStandardLayout(group("and", group("or", expression("A"))))).toBe(false);
+    });
+    test("an expression directly under the root is not standard", () => {
+        expect(isStandardLayout(group("or", expression("A")))).toBe(false);
+    });
+    test("a group nested three levels deep is not standard", () => {
+        expect(isStandardLayout(group("or", group("and", group("or", expression("A")))))).toBe(false);
+    });
+    test("null and bare expressions are not standard", () => {
+        expect(isStandardLayout(null)).toBe(false);
+        expect(isStandardLayout(expression("A"))).toBe(false);
+    });
+});
+describe("coerceToStandardLayout", () => {
+    test("null becomes an empty or/and pair", () => {
+        expect(coerceToStandardLayout(null)).toEqual(group("or", group("and")));
+    });
+    test("a bare expression is wrapped in an or/and pair", () => {
+        let result = coerceToStandardLayout(expression("Name"));
+        expect(result.mode).toBe("or");
+        expect(result.items).toHaveLength(1);
+        expect(result.items[0].mode).toBe("and");
+        expect(result.items[0].items).toEqual([expression("Name")]);
+    });
+    test("an and group becomes a single group inside an or group", () => {
+        let result = coerceToStandardLayout(group("and", expression("A"), expression("B")));
+        expect(result.mode).toBe("or");
+        expect(result.items).toHaveLength(1);
+        expect(countExpressions(result)).toBe(2);
+    });
+    test("an or group keeps one and group per item", () => {
+        let result = coerceToStandardLayout(group("or", expression("A"), group("and", expression("B"), expression("C"))));
+        expect(result.items).toHaveLength(2);
+        expect(result.items[0].items).toHaveLength(1);
+        expect(result.items[1].items).toHaveLength(2);
+    });
+    test("deeper nesting is flattened, keeping every expression", () => {
+        let nested = group("and", expression("A"), group("or", expression("B"), group("and", expression("C"))));
+        let result = coerceToStandardLayout(nested);
+        expect(result.items).toHaveLength(1);
+        expect(countExpressions(result)).toBe(3);
+    });
+    test("an empty or group still yields one editable group", () => {
+        let result = coerceToStandardLayout(group("or"));
+        expect(result.items).toHaveLength(1);
+        expect(result.items[0].items).toEqual([]);
+    });
+    test("is idempotent", () => {
+        let once = coerceToStandardLayout(group("or", expression("A"), expression("B")));
+        expect(coerceToStandardLayout(once)).toEqual(once);
+    });
+});

package/es/filter/tree.d.ts

@@ -0,0 +1,70 @@
+import type { FieldMetadata, FilterExpression, FilterGroup, FilterOperator, FilterTree } from "./types.js";
+/**
+ * Path to a node in a filter tree, as a list of item indexes from the root
+ * group. The root itself is the empty path.
+ *
+ * @example
+ * ```ts
+ * // The second condition of the first group
+ * let path: FilterPath = [0, 1];
+ * ```
+ */
+export type FilterPath = number[];
+export type FilterNode = FilterGroup | FilterExpression;
+/**
+ * Creates the default empty filter: a single `and` group with no conditions.
+ */
+export declare function createEmptyFilter(): FilterTree;
+export declare function createEmptyGroup(mode?: FilterGroup["mode"]): FilterGroup;
+export declare function isGroup(item: FilterNode): item is FilterGroup;
+export declare function isExpression(item: FilterNode): item is FilterExpression;
+/**
+ * Normalizes any filter value into a tree the editor can render, without
+ * changing its structure. An expression is wrapped in a group; a missing filter
+ * becomes the default layout.
+ */
+export declare function toFilterTree(filter: FilterNode | null | undefined): FilterTree;
+/**
+ * True when the filter contains no expressions. An empty filter must not be
+ * saved or applied.
+ */
+export declare function isEmptyFilter(filter: FilterNode | null | undefined): boolean;
+export declare function countExpressions(filter: FilterNode | null | undefined): number;
+/**
+ * Removes incomplete expressions and empty groups from the whole tree. Returns
+ * null when nothing is left. Use before applying a filter to a data object so
+ * incomplete rows are not sent.
+ */
+export declare function pruneFilter(filter: FilterNode | null | undefined): FilterGroup | null;
+/**
+ * True when an expression has everything it needs to be sent to the server.
+ */
+export declare function isCompleteExpression(item: FilterNode): boolean;
+/**
+ * Creates an expression for a field, using the field's default operator and an
+ * empty value of the right shape.
+ */
+export declare function createExpression(field: FieldMetadata, operator?: FilterOperator): FilterExpression;
+/**
+ * Returns a copy of the expression with a new operator, adjusting the value to
+ * the new operator's arity and the value type accordingly.
+ */
+export declare function changeOperator(expression: FilterExpression, operator: FilterOperator, field: Pick<FieldMetadata, "type">): FilterExpression;
+/** Returns the node at `path`, or null when the path does not exist. */
+export declare function getNodeAtPath(filter: FilterNode, path: FilterPath): FilterNode | null;
+/**
+ * Returns a copy of the tree with `updater` applied to the node at `path`.
+ * Returning null removes the node. An unknown path leaves the tree untouched.
+ */
+export declare function updateNodeAtPath<T extends FilterNode>(filter: T, path: FilterPath, updater: (node: FilterNode) => FilterNode | null): T;
+/** Returns a copy of the tree with `node` appended to the group at `path`. */
+export declare function insertNodeAtPath<T extends FilterNode>(filter: T, path: FilterPath, node: FilterNode): T;
+/**
+ * Returns a copy of the tree with the node at `path` removed. The root is never
+ * removed; it is reset to the default layout instead.
+ */
+export declare function removeNodeAtPath<T extends FilterNode>(filter: T, path: FilterPath): T;
+/** Returns a copy of the tree with the mode of the group at `path` changed. */
+export declare function setGroupMode<T extends FilterNode>(filter: T, path: FilterPath, mode: FilterGroup["mode"]): T;
+/** Returns a copy of the tree with an empty group appended to the group at `path`. */
+export declare function addGroupAtPath<T extends FilterNode>(filter: T, path?: FilterPath): T;