@olenbetong/appframe-core 2.11.9 → 2.12.0

package/src/filter/savedFilters.ts

@@ -0,0 +1,192 @@
+/**
+ * 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 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 function toSavedFilter(record: SavedFilterRecord): SavedFilter {
+	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: string | null | undefined): FilterAccessLevel {
+	if (value === "Manager" || value === "Editor") return value;
+
+	return "Reader";
+}
+
+function toBoolean(value: string | boolean | number | null | undefined): boolean {
+	if (typeof value === "string") return value.toLowerCase() === "true";
+
+	return Boolean(value);
+}
+
+function toDate(value: Date | string | null | undefined): Date | null {
+	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: SavedFilterRecord[]): SavedFilter[] {
+	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: SavedFilter[]): { mine: SavedFilter[]; shared: SavedFilter[] } {
+	let mine: SavedFilter[] = [];
+	let shared: SavedFilter[] = [];
+
+	for (let filter of filters) {
+		if (filter.createdByUser) {
+			mine.push(filter);
+		} else {
+			shared.push(filter);
+		}
+	}
+
+	return { mine, shared };
+}
+
+export function findSavedFilter(filters: SavedFilter[], filterId: number | null | undefined) {
+	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: SavedFilter): boolean {
+	return filter.accessLevel === "Editor" || filter.accessLevel === "Manager";
+}
+
+/** True when the user may change who the filter is shared with. */
+export function canShareSavedFilter(filter: SavedFilter): boolean {
+	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: SavedFilter): boolean {
+	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/src/filter/standardLayout.test.ts

@@ -0,0 +1,88 @@
+import type { FilterExpression, FilterGroup } from "./types.js";
+import { describe, expect, test } from "vitest";
+
+import { coerceToStandardLayout, isStandardLayout } from "./standardLayout.js";
+import { countExpressions } from "./tree.js";
+
+function expression(column: string, operator = "equals", value: FilterExpression["value"] = "x"): FilterExpression {
+	return { type: "expression", column, operator, value, valueType: "string" };
+}
+
+function group(mode: "and" | "or", ...items: Array<FilterGroup | FilterExpression>): FilterGroup {
+	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] as FilterGroup).mode).toBe("and");
+		expect((result.items[0] as FilterGroup).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] as FilterGroup).items).toHaveLength(1);
+		expect((result.items[1] as FilterGroup).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] as FilterGroup).items).toEqual([]);
+	});
+
+	test("is idempotent", () => {
+		let once = coerceToStandardLayout(group("or", expression("A"), expression("B")));
+
+		expect(coerceToStandardLayout(once)).toEqual(once);
+	});
+});

package/src/filter/standardLayout.ts

@@ -0,0 +1,65 @@
+import { isExpression, isGroup } from "./tree.js";
+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 function isStandardLayout(filter: FilterGroup | FilterExpression | null | undefined): boolean {
+	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: FilterGroup | FilterExpression | null | undefined): FilterTree {
+	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: FilterExpression[] = [];
+			collectExpressions(item, expressions);
+
+			return { type: "group", mode: "and", items: expressions } satisfies FilterGroup;
+		});
+
+		return {
+			type: "group",
+			mode: "or",
+			items: groups.length > 0 ? groups : [{ type: "group", mode: "and", items: [] }],
+		};
+	}
+
+	let expressions: FilterExpression[] = [];
+	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: FilterGroup | FilterExpression, into: FilterExpression[]) {
+	if (isExpression(item)) {
+		into.push(item);
+		return;
+	}
+
+	for (let child of item.items) {
+		collectExpressions(child, into);
+	}
+}

package/src/filter/tree.test.ts

@@ -0,0 +1,258 @@
+import type { FilterExpression, FilterGroup } from "./types.js";
+import { describe, expect, test } from "vitest";
+
+import {
+	addGroupAtPath,
+	changeOperator,
+	countExpressions,
+	createEmptyFilter,
+	createExpression,
+	getNodeAtPath,
+	insertNodeAtPath,
+	isCompleteExpression,
+	isEmptyFilter,
+	pruneFilter,
+	removeNodeAtPath,
+	setGroupMode,
+	toFilterTree,
+	updateNodeAtPath,
+} from "./tree.js";
+
+function expression(column: string, operator = "equals", value: FilterExpression["value"] = "x"): FilterExpression {
+	return { type: "expression", column, operator, value, valueType: "string" };
+}
+
+function group(mode: "and" | "or", ...items: Array<FilterGroup | FilterExpression>): FilterGroup {
+	return { type: "group", mode, items };
+}
+
+describe("createEmptyFilter", () => {
+	test("creates a single empty and group", () => {
+		expect(createEmptyFilter()).toEqual({ type: "group", mode: "and", items: [] });
+	});
+});
+
+describe("toFilterTree", () => {
+	test("null becomes the default layout", () => {
+		expect(toFilterTree(null)).toEqual(createEmptyFilter());
+	});
+
+	test("a bare expression is wrapped in an and group", () => {
+		expect(toFilterTree(expression("Name"))).toEqual(group("and", expression("Name")));
+	});
+
+	test("nesting is preserved", () => {
+		let nested = group("and", expression("A"), group("or", expression("B"), expression("C")));
+
+		expect(toFilterTree(nested)).toBe(nested);
+	});
+});
+
+describe("isEmptyFilter", () => {
+	test("a fresh filter is empty", () => {
+		expect(isEmptyFilter(createEmptyFilter())).toBe(true);
+	});
+
+	test("null is empty", () => {
+		expect(isEmptyFilter(null)).toBe(true);
+	});
+
+	test("a filter with an expression is not empty", () => {
+		expect(isEmptyFilter(insertNodeAtPath(createEmptyFilter(), [], expression("A")))).toBe(false);
+	});
+});
+
+describe("isCompleteExpression", () => {
+	test("parameterless operators need no value", () => {
+		expect(isCompleteExpression(expression("A", "isnull", null))).toBe(true);
+		expect(isCompleteExpression(expression("A", "istrue", null))).toBe(true);
+	});
+
+	test("a missing column makes the expression incomplete", () => {
+		expect(isCompleteExpression(expression("", "equals", "x"))).toBe(false);
+	});
+
+	test("an empty value makes the expression incomplete", () => {
+		expect(isCompleteExpression(expression("A", "equals", ""))).toBe(false);
+		expect(isCompleteExpression(expression("A", "equals", null))).toBe(false);
+	});
+
+	test("between needs both values", () => {
+		expect(isCompleteExpression(expression("A", "between", ["1", "2"]))).toBe(true);
+		expect(isCompleteExpression(expression("A", "between", ["1", ""]))).toBe(false);
+		expect(isCompleteExpression(expression("A", "between", ["1"]))).toBe(false);
+	});
+
+	test("in list needs at least one value", () => {
+		expect(isCompleteExpression(expression("A", "inlist", ["1"]))).toBe(true);
+		expect(isCompleteExpression(expression("A", "inlist", []))).toBe(false);
+	});
+
+	test("PascalCase operators are recognised", () => {
+		expect(isCompleteExpression(expression("A", "IsNull", null))).toBe(true);
+	});
+});
+
+describe("pruneFilter", () => {
+	test("returns null when nothing is complete", () => {
+		let filter = insertNodeAtPath(createEmptyFilter(), [], expression("A", "equals", ""));
+
+		expect(pruneFilter(filter)).toBeNull();
+	});
+
+	test("drops incomplete expressions and empty groups", () => {
+		let filter = createEmptyFilter();
+		filter = insertNodeAtPath(filter, [], expression("A"));
+		filter = insertNodeAtPath(filter, [], expression("B", "equals", ""));
+		filter = addGroupAtPath(filter);
+		filter = insertNodeAtPath(filter, [2], expression("C", "equals", ""));
+
+		let pruned = pruneFilter(filter);
+
+		expect(pruned?.items).toHaveLength(1);
+		expect(countExpressions(pruned)).toBe(1);
+	});
+
+	test("keeps complete groups untouched", () => {
+		let filter = insertNodeAtPath(createEmptyFilter(), [], expression("A"));
+
+		expect(pruneFilter(filter)).toEqual(group("and", expression("A")));
+	});
+
+	test("prunes nested groups recursively", () => {
+		let filter = group(
+			"and",
+			expression("A"),
+			group("or", expression("B", "equals", ""), group("and", expression("C"))),
+		);
+
+		expect(pruneFilter(filter)).toEqual(group("and", expression("A"), group("or", group("and", expression("C")))));
+	});
+});
+
+describe("createExpression", () => {
+	test("uses the field's default operator and an empty value", () => {
+		expect(createExpression({ name: "Name", type: "string" })).toEqual({
+			type: "expression",
+			column: "Name",
+			operator: "beginswith",
+			value: "",
+			valueType: "string",
+		});
+	});
+
+	test("parameterless default operators get a null value", () => {
+		expect(createExpression({ name: "Active", type: "boolean" })).toMatchObject({
+			operator: "istrue",
+			value: null,
+			valueType: "null",
+		});
+	});
+
+	test("an explicit operator shapes the value", () => {
+		expect(createExpression({ name: "Amount", type: "number" }, "between")).toMatchObject({
+			value: ["", ""],
+			valueType: "number",
+		});
+		expect(createExpression({ name: "Amount", type: "number" }, "inlist")).toMatchObject({ value: [] });
+	});
+});
+
+describe("changeOperator", () => {
+	test("keeps the value when the arity is unchanged", () => {
+		let result = changeOperator(expression("A", "equals", "abc"), "contains", { type: "string" });
+
+		expect(result).toMatchObject({ operator: "contains", value: "abc" });
+	});
+
+	test("resets the value when the arity changes", () => {
+		let result = changeOperator(expression("A", "equals", "abc"), "between", { type: "string" });
+
+		expect(result.value).toEqual(["", ""]);
+	});
+
+	test("switching to a parameterless operator clears the value", () => {
+		let result = changeOperator(expression("A", "equals", "abc"), "isnull", { type: "string" });
+
+		expect(result).toMatchObject({ value: null, valueType: "null" });
+	});
+
+	test("a dynamic value survives a same-arity operator change", () => {
+		let dynamic: FilterExpression = {
+			type: "expression",
+			column: "Created",
+			operator: "equals",
+			value: "ThisMonth",
+			valueType: "special",
+		};
+		let result = changeOperator(dynamic, "greaterthan", { type: "date" });
+
+		expect(result).toMatchObject({ valueType: "special", value: "ThisMonth" });
+	});
+});
+
+describe("path helpers", () => {
+	let nested = group("or", group("and", expression("A"), group("or", expression("B"), expression("C"))));
+
+	test("getNodeAtPath walks into nested groups", () => {
+		expect(getNodeAtPath(nested, [])).toBe(nested);
+		expect(getNodeAtPath(nested, [0, 0])).toEqual(expression("A"));
+		expect(getNodeAtPath(nested, [0, 1, 1])).toEqual(expression("C"));
+	});
+
+	test("getNodeAtPath returns null for an unknown path", () => {
+		expect(getNodeAtPath(nested, [5])).toBeNull();
+		expect(getNodeAtPath(nested, [0, 0, 0])).toBeNull();
+	});
+
+	test("insertNodeAtPath appends to a nested group", () => {
+		let result = insertNodeAtPath(nested, [0, 1], expression("D"));
+
+		expect(countExpressions(result)).toBe(4);
+		expect(getNodeAtPath(result, [0, 1, 2])).toEqual(expression("D"));
+	});
+
+	test("insertNodeAtPath ignores an unknown path", () => {
+		expect(insertNodeAtPath(nested, [5], expression("D"))).toBe(nested);
+	});
+
+	test("updateNodeAtPath replaces one node", () => {
+		let result = updateNodeAtPath(nested, [0, 1, 0], (node) => ({ ...(node as FilterExpression), value: "changed" }));
+
+		expect(getNodeAtPath(result, [0, 1, 0])).toMatchObject({ value: "changed" });
+		expect(getNodeAtPath(nested, [0, 1, 0])).toMatchObject({ value: "x" });
+	});
+
+	test("removeNodeAtPath removes a nested node", () => {
+		let result = removeNodeAtPath(nested, [0, 1, 0]);
+
+		expect(countExpressions(result)).toBe(2);
+	});
+
+	test("removing the root resets to the default layout", () => {
+		expect(removeNodeAtPath(nested, [])).toEqual(createEmptyFilter());
+	});
+
+	test("setGroupMode changes the mode of the group at the path", () => {
+		expect(setGroupMode(nested, [], "and").mode).toBe("and");
+		expect((getNodeAtPath(setGroupMode(nested, [0], "or"), [0]) as FilterGroup).mode).toBe("or");
+	});
+
+	test("setGroupMode leaves expressions alone", () => {
+		expect(setGroupMode(nested, [0, 0], "or")).toEqual(nested);
+	});
+
+	test("addGroupAtPath uses the opposite mode to its parent", () => {
+		let withGroup = addGroupAtPath(createEmptyFilter());
+
+		expect((getNodeAtPath(withGroup, [0]) as FilterGroup).mode).toBe("or");
+		expect((getNodeAtPath(addGroupAtPath(withGroup, [0]), [0, 0]) as FilterGroup).mode).toBe("and");
+	});
+
+	test("mutations do not modify the original filter", () => {
+		let filter = createEmptyFilter();
+		insertNodeAtPath(filter, [], expression("A"));
+
+		expect(countExpressions(filter)).toBe(0);
+	});
+});