@olenbetong/appframe-core 2.11.10 → 2.13.0

package/src/filter/operators.ts

@@ -0,0 +1,258 @@
+import { getLocalizedString } from "../getLocalizedString.js";
+import type { DynamicValue, FieldMetadata, FilterFieldType, FilterOperator, FilterValueType } from "./types.js";
+
+/**
+ * Operators that take no value at all.
+ *
+ * `eOperators.ParameterLessChecks` plus the blank checks.
+ */
+const PARAMETERLESS_OPERATORS: FilterOperator[] = ["isnull", "isnotnull", "istrue", "isfalse", "isblank", "isnotblank"];
+
+/** Operators whose value is a two element `[from, to]` array. */
+const PAIR_OPERATORS: FilterOperator[] = ["between", "notbetween", "datebetween", "datenotbetween"];
+
+/** Operators whose value is an array of values. */
+const LIST_OPERATORS: FilterOperator[] = ["inlist", "notinlist"];
+
+/** How many values an operator needs. */
+export type OperatorArity = "none" | "single" | "pair" | "list";
+
+export function getOperatorArity(operator: FilterOperator): OperatorArity {
+	if (PARAMETERLESS_OPERATORS.includes(operator)) return "none";
+	if (PAIR_OPERATORS.includes(operator)) return "pair";
+	if (LIST_OPERATORS.includes(operator)) return "list";
+	return "single";
+}
+
+/**
+ * Operator labels, keyed by operator. Comparison operators have a different
+ * label for dates than for numbers, matching the Windows filter editor.
+ *
+ * @see `appframe/Appframe3.Win/Controls/afFilterEditor/Utils/FilterLineControlUtils.vb`
+ */
+const OPERATOR_LABELS: Record<FilterOperator, string> = {
+	equals: "Equal to",
+	notequals: "Not equal to",
+	greaterthan: "Greater than",
+	greaterthanorequal: "Greater than or equal to",
+	lessthan: "Less than",
+	lessthanorequal: "Less than or equal to",
+	beginswith: "Begins with",
+	notbeginswith: "Does not begin with",
+	endswith: "Ends with",
+	notendswith: "Does not end with",
+	contains: "Contains",
+	notcontains: "Does not contain",
+	like: "Like",
+	notlike: "Not like",
+	isnull: "Is null",
+	isnotnull: "Is not null",
+	isblank: "Is empty",
+	isnotblank: "Is not empty",
+	istrue: "Is true",
+	isfalse: "Is false",
+	inlist: "In list",
+	notinlist: "Not in list",
+	between: "Between",
+	notbetween: "Not between",
+	dateequals: "Equal to",
+	notdatequals: "Not equal to",
+	dategreaterthan: "After",
+	dategreaterthanorequal: "On or after",
+	datelessthan: "Before",
+	datelessthanorequal: "Up to",
+	datebetween: "Between",
+	datenotbetween: "Not between",
+};
+
+/** Comparison operator labels used for date and time fields. */
+const DATE_OPERATOR_LABELS: Partial<Record<FilterOperator, string>> = {
+	greaterthan: "After",
+	greaterthanorequal: "On or after",
+	lessthan: "Before",
+	lessthanorequal: "Up to",
+};
+
+/**
+ * Returns the localized label for an operator. Date fields get the
+ * "After"/"Before" wording instead of "Greater than"/"Less than".
+ */
+export function getOperatorLabel(operator: FilterOperator, fieldType?: FilterFieldType): string {
+	let isDate = fieldType === "date" || fieldType === "datetime";
+	let label = (isDate ? DATE_OPERATOR_LABELS[operator] : undefined) ?? OPERATOR_LABELS[operator];
+
+	return getLocalizedString(label ?? operator);
+}
+
+const EQUALITY: FilterOperator[] = ["equals", "notequals"];
+const LIST_CHECKS: FilterOperator[] = ["inlist", "notinlist"];
+const RANGE: FilterOperator[] = ["between", "notbetween"];
+const COMPARISONS: FilterOperator[] = ["greaterthan", "greaterthanorequal", "lessthan", "lessthanorequal"];
+const STRING_CHECKS: FilterOperator[] = [
+	"contains",
+	"notcontains",
+	"beginswith",
+	"notbeginswith",
+	"endswith",
+	"notendswith",
+	"isblank",
+	"isnotblank",
+];
+
+/**
+ * Operators offered per field type, in the order the Windows filter editor
+ * presents them.
+ */
+const OPERATORS_BY_TYPE: Record<FilterFieldType, FilterOperator[]> = {
+	date: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+	datetime: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+	number: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+	boolean: ["istrue", "isfalse"],
+	string: [...EQUALITY, ...STRING_CHECKS, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+	uniqueidentifier: [...EQUALITY, ...STRING_CHECKS, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+};
+
+/**
+ * Default operator per field type.
+ *
+ * Text defaults to `contains` because a substring search is what people
+ * reach for when they type into a filter box without picking an operator —
+ * `beginswith` silently misses matches in the middle of the value.
+ */
+const DEFAULT_OPERATOR_BY_TYPE: Record<FilterFieldType, FilterOperator> = {
+	date: "equals",
+	datetime: "equals",
+	number: "equals",
+	boolean: "istrue",
+	string: "contains",
+	uniqueidentifier: "beginswith",
+};
+
+/**
+ * Returns the operators available for a field. Nullable fields additionally get
+ * the null checks. Boolean fields never get null checks, since `istrue` and
+ * `isfalse` already cover the parameterless cases.
+ */
+export function getOperatorsForField(field: Pick<FieldMetadata, "type" | "nullable">): FilterOperator[] {
+	let operators = [...(OPERATORS_BY_TYPE[field.type] ?? OPERATORS_BY_TYPE.string)];
+
+	if (field.nullable && field.type !== "boolean") {
+		operators.push("isnull", "isnotnull");
+	}
+
+	return operators;
+}
+
+export function getDefaultOperator(field: Pick<FieldMetadata, "type">): FilterOperator {
+	return DEFAULT_OPERATOR_BY_TYPE[field.type] ?? "equals";
+}
+
+/**
+ * The `valueType` to send for a field/operator combination.
+ *
+ * Parameterless operators send `"null"`, list and range operators send
+ * `"array"`, everything else sends the field's own value type.
+ */
+export function getValueType(field: Pick<FieldMetadata, "type">, operator: FilterOperator): FilterValueType {
+	if (getOperatorArity(operator) === "none") return "null";
+
+	switch (field.type) {
+		case "number":
+			return "number";
+		case "boolean":
+			return "boolean";
+		case "date":
+		case "datetime":
+			return "datetime";
+		case "uniqueidentifier":
+			return "uniqueidentifier";
+		default:
+			return "string";
+	}
+}
+
+/** Relative date values offered in the date value editor, in menu order. */
+export const RELATIVE_DATE_VALUES: DynamicValue[] = [
+	"Yesterday",
+	"Today",
+	"Tomorrow",
+	"ThisWeek",
+	"ThisMonth",
+	"ThisYear",
+	"LastWeek",
+	"LastMonth",
+	"LastYear",
+	"NextWeek",
+	"NextMonth",
+	"NextYear",
+];
+
+const DYNAMIC_VALUE_LABELS: Record<DynamicValue, string> = {
+	CurrentUser: "Current user",
+	Yesterday: "Yesterday",
+	Today: "Today",
+	Tomorrow: "Tomorrow",
+	ThisWeek: "This week",
+	ThisMonth: "This month",
+	ThisYear: "This year",
+	LastWeek: "Last week",
+	LastMonth: "Last month",
+	LastYear: "Last year",
+	NextWeek: "Next week",
+	NextMonth: "Next month",
+	NextYear: "Next year",
+	UserYesterday: "Yesterday",
+	UserToday: "Today",
+	UserTomorrow: "Tomorrow",
+	UserThisWeek: "This week",
+	UserThisMonth: "This month",
+	UserThisYear: "This year",
+	UserLastWeek: "Last week",
+	UserLastMonth: "Last month",
+	UserLastYear: "Last year",
+	UserNextWeek: "Next week",
+	UserNextMonth: "Next month",
+	UserNextYear: "Next year",
+};
+
+export function getDynamicValueLabel(value: DynamicValue): string {
+	return getLocalizedString(DYNAMIC_VALUE_LABELS[value] ?? value);
+}
+
+/**
+ * Returns the dynamic ("special") values that can be used with a field. Date
+ * fields get the relative dates; string fields can be compared to the current
+ * user name.
+ */
+export function getDynamicValuesForField(field: Pick<FieldMetadata, "type">): DynamicValue[] {
+	if (field.type === "date" || field.type === "datetime") return [...RELATIVE_DATE_VALUES];
+	if (field.type === "string") return ["CurrentUser"];
+
+	return [];
+}
+
+/**
+ * Aliases for names `eOperators.ToString()` can produce that are not operators
+ * in their own right. `Not` is the bare negation flag (i.e. "not equal to"),
+ * `Tweens` shares its numeric value with `NotBetween`, and combined flags are
+ * rendered as a comma separated list.
+ *
+ * @see `FilterElementConverter.FilterExpressionToDictionary`
+ */
+const OPERATOR_ALIASES: Record<string, FilterOperator> = {
+	not: "notequals",
+	tweens: "notbetween",
+	notdate: "notdatequals",
+	// The enum member is `NotDateEquals`, but the wire format drops an "e".
+	notdateequals: "notdatequals",
+};
+
+/**
+ * Normalizes an operator string coming from the server or from another filter
+ * producer (`AfGrid` emits PascalCase names) to the canonical lower-case form.
+ */
+export function normalizeOperator(operator: string): FilterOperator {
+	let normalized = operator.toLowerCase().replace(/[\s,]/g, "");
+
+	return OPERATOR_ALIASES[normalized] ?? (normalized as FilterOperator);
+}

package/src/filter/savedFilters.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from "vitest";
+
+import {
+	canDeleteSavedFilter,
+	canEditSavedFilter,
+	canRenameSavedFilter,
+	canShareSavedFilter,
+	findSavedFilter,
+	NO_FILTER_ID,
+	partitionSavedFilters,
+	type SavedFilterRecord,
+	toSavedFilter,
+	toSavedFilters,
+} from "./savedFilters.js";
+
+function record(overrides: SavedFilterRecord = {}): SavedFilterRecord {
+	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/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);
+	});
+});