@remit/ui 0.0.67 → 0.0.68

package/src/lib/folder-tree.test.ts

@@ -0,0 +1,281 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	collapseFolderTree,
+	type FolderTreeNode,
+	filterFolderTree,
+	folderAncestors,
+	folderDepth,
+	folderParent,
+	matchesQuery,
+	orderFolderNodes,
+	queryExpandedPaths,
+	withCreateRows,
+} from "./folder-tree.js";
+
+const node = (
+	id: string,
+	label: string,
+	path: string,
+	isCurrent?: boolean,
+): FolderTreeNode => ({ id, label, path, isCurrent });
+
+const folders: FolderTreeNode[] = [
+	node("inbox", "Inbox", "INBOX", true),
+	node("hotels", "Hotels", "Travel/Hotels"),
+	node("archive", "Archive", "Archive"),
+	node("travel", "Travel", "Travel"),
+	node("receipts", "Receipts", "Travel/Hotels/Receipts"),
+	node("trash", "Trash", "Deleted Messages"),
+];
+
+const ordered = orderFolderNodes(folders, "/");
+
+const paths = (rows: readonly { folder: FolderTreeNode }[]): string[] =>
+	rows.map((row) => row.folder.path);
+
+describe("folder paths", () => {
+	it("reads the parent, the depth and the ancestors off the path", () => {
+		assert.equal(folderParent("Travel/Hotels/Receipts", "/"), "Travel/Hotels");
+		assert.equal(folderParent("Archive", "/"), "");
+		assert.equal(folderDepth("Travel/Hotels/Receipts", "/"), 2);
+		assert.deepEqual(folderAncestors("Travel/Hotels/Receipts", "/"), [
+			"Travel/Hotels",
+			"Travel",
+		]);
+	});
+
+	it("splits on the provider's separator", () => {
+		assert.equal(folderParent("Travel.Hotels", "."), "Travel");
+		assert.equal(folderDepth("Travel.Hotels", "."), 1);
+		assert.deepEqual(folderAncestors("Travel.Hotels", "."), ["Travel"]);
+	});
+});
+
+describe("folder ordering", () => {
+	it("puts every child straight after its parent", () => {
+		assert.deepEqual(
+			orderFolderNodes(folders, "/").map((folder) => folder.path),
+			[
+				"INBOX",
+				"Archive",
+				"Travel",
+				"Travel/Hotels",
+				"Travel/Hotels/Receipts",
+				"Deleted Messages",
+			],
+		);
+	});
+
+	it("renders a folder whose parent is absent as a root", () => {
+		const orphaned = [
+			node("archive", "Archive", "Archive"),
+			node("apollo", "Apollo", "Work/Projects/Apollo"),
+		];
+		assert.deepEqual(
+			orderFolderNodes(orphaned, "/").map((folder) => folder.path),
+			["Archive", "Work/Projects/Apollo"],
+		);
+	});
+
+	it("nests on the provider's separator", () => {
+		const dotted = [
+			node("child", "Hotels", "Travel.Hotels"),
+			node("other", "Archive", "Archive"),
+			node("parent", "Travel", "Travel"),
+		];
+		assert.deepEqual(
+			orderFolderNodes(dotted, ".").map((folder) => folder.path),
+			["Archive", "Travel", "Travel.Hotels"],
+		);
+	});
+});
+
+describe("collapsing", () => {
+	it("shows the top level and nothing under it", () => {
+		const rows = collapseFolderTree(ordered, new Set(), "/");
+		assert.deepEqual(paths(rows), [
+			"INBOX",
+			"Archive",
+			"Travel",
+			"Deleted Messages",
+		]);
+	});
+
+	it("reveals only the children of what is open", () => {
+		const rows = collapseFolderTree(ordered, new Set(["Travel"]), "/");
+		assert.deepEqual(paths(rows), [
+			"INBOX",
+			"Archive",
+			"Travel",
+			"Travel/Hotels",
+			"Deleted Messages",
+		]);
+	});
+
+	it("needs every ancestor open to reach a grandchild", () => {
+		assert.deepEqual(
+			paths(collapseFolderTree(ordered, new Set(["Travel/Hotels"]), "/")),
+			["INBOX", "Archive", "Travel", "Deleted Messages"],
+		);
+		assert.deepEqual(
+			paths(
+				collapseFolderTree(ordered, new Set(["Travel", "Travel/Hotels"]), "/"),
+			),
+			[
+				"INBOX",
+				"Archive",
+				"Travel",
+				"Travel/Hotels",
+				"Travel/Hotels/Receipts",
+				"Deleted Messages",
+			],
+		);
+	});
+
+	it("marks what is open on the row", () => {
+		const rows = collapseFolderTree(ordered, new Set(["Travel"]), "/");
+		assert.deepEqual(
+			rows.map((row) => row.expanded),
+			[false, false, true, false, false],
+		);
+	});
+
+	it("shows a folder whose parent is absent from the list", () => {
+		const orphaned = orderFolderNodes(
+			[
+				node("archive", "Archive", "Archive"),
+				node("apollo", "Apollo", "Work/Projects/Apollo"),
+			],
+			"/",
+		);
+		assert.deepEqual(paths(collapseFolderTree(orphaned, new Set(), "/")), [
+			"Archive",
+			"Work/Projects/Apollo",
+		]);
+	});
+});
+
+describe("filtering", () => {
+	it("matches on the label", () => {
+		assert.equal(matchesQuery(node("a", "Archive", "Archive"), "arch"), true);
+	});
+
+	it("matches on the path, so a role-labelled folder is still findable", () => {
+		assert.equal(
+			matchesQuery(node("t", "Trash", "Deleted Messages"), "deleted"),
+			true,
+		);
+	});
+
+	it("keeps the ancestors of a match on screen", () => {
+		const rows = filterFolderTree(ordered, "receipts", "/");
+		assert.deepEqual(paths(rows), [
+			"Travel",
+			"Travel/Hotels",
+			"Travel/Hotels/Receipts",
+		]);
+	});
+
+	it("marks an ancestor kept for context as no match of its own", () => {
+		const rows = filterFolderTree(ordered, "receipts", "/");
+		assert.deepEqual(
+			rows.map((row) => row.context),
+			[true, true, false],
+		);
+	});
+
+	it("keeps a matching ancestor a match", () => {
+		const rows = filterFolderTree(ordered, "travel", "/");
+		assert.deepEqual(
+			rows.map((row) => row.context),
+			[false, false, false],
+		);
+	});
+
+	it("opens the ancestors a match hides behind", () => {
+		assert.deepEqual([...queryExpandedPaths(ordered, "receipts", "/")].sort(), [
+			"Travel",
+			"Travel/Hotels",
+		]);
+	});
+
+	it("opens nothing on an empty query, so the list stays as it was", () => {
+		assert.equal(queryExpandedPaths(ordered, "", "/").size, 0);
+	});
+
+	it("carries the depth the row indents by", () => {
+		const rows = filterFolderTree(ordered, "", "/");
+		assert.deepEqual(
+			rows.map((row) => row.depth),
+			[0, 0, 0, 1, 2, 0],
+		);
+	});
+
+	it("marks what is open on a filtered row", () => {
+		const rows = filterFolderTree(ordered, "hotels", "/", new Set(["Travel"]));
+		assert.deepEqual(
+			rows.map((row) => row.expanded),
+			[true, false, false],
+		);
+	});
+
+	it("narrows to nothing when the query matches no folder", () => {
+		assert.deepEqual(filterFolderTree(ordered, "zzz", "/"), []);
+	});
+});
+
+describe("create rows", () => {
+	const kinds = (expanded: string[]) =>
+		withCreateRows(
+			collapseFolderTree(ordered, new Set(expanded), "/"),
+			"/",
+		).map((entry) =>
+			entry.kind === "create"
+				? `new inside ${entry.parent.path} @${entry.depth}`
+				: entry.row.folder.path,
+		);
+
+	it("offers none while everything is closed", () => {
+		assert.deepEqual(kinds([]), [
+			"INBOX",
+			"Archive",
+			"Travel",
+			"Deleted Messages",
+		]);
+	});
+
+	it("puts the action after the children of the folder it belongs to", () => {
+		assert.deepEqual(kinds(["Travel"]), [
+			"INBOX",
+			"Archive",
+			"Travel",
+			"Travel/Hotels",
+			"new inside Travel @1",
+			"Deleted Messages",
+		]);
+	});
+
+	it("closes the deepest branch first when several are open", () => {
+		assert.deepEqual(kinds(["Travel", "Travel/Hotels"]), [
+			"INBOX",
+			"Archive",
+			"Travel",
+			"Travel/Hotels",
+			"Travel/Hotels/Receipts",
+			"new inside Travel/Hotels @2",
+			"new inside Travel @1",
+			"Deleted Messages",
+		]);
+	});
+
+	it("offers the action on an open folder with no children", () => {
+		assert.deepEqual(kinds(["Archive"]), [
+			"INBOX",
+			"Archive",
+			"new inside Archive @1",
+			"Travel",
+			"Deleted Messages",
+		]);
+	});
+});

package/src/lib/folder-tree.ts

@@ -0,0 +1,201 @@
+export interface FolderTreeNode {
+	/** Stable identity passed back to the surface that owns the choice. */
+	id: string;
+	/**
+	 * What the row reads as. An appointed folder is labelled by its role, so
+	 * `Deleted Messages` shows as "Trash" while still nesting under its real
+	 * path — which is why the label is not derived from the path.
+	 */
+	label: string;
+	/** The provider path. Nesting, indentation and filtering all read this. */
+	path: string;
+	/**
+	 * Where the messages live now. A "you are here" marker: never a target, and
+	 * rendered as a marker rather than a disabled control.
+	 */
+	isCurrent?: boolean;
+}
+
+export interface FolderTreeRow {
+	folder: FolderTreeNode;
+	depth: number;
+	/**
+	 * On screen only to keep a match below it in place. It reads as the branch
+	 * it is, not as an answer to what was typed.
+	 */
+	context: boolean;
+	/** Its children and its create action are on screen. */
+	expanded: boolean;
+}
+
+export type FolderTreeDisplayRow =
+	| { kind: "folder"; row: FolderTreeRow; index: number }
+	| { kind: "create"; parent: FolderTreeNode; depth: number };
+
+export const folderParent = (path: string, delimiter: string): string => {
+	const cut = path.lastIndexOf(delimiter);
+	return cut === -1 ? "" : path.slice(0, cut);
+};
+
+export const folderDepth = (path: string, delimiter: string): number =>
+	path.split(delimiter).length - 1;
+
+export const folderAncestors = (path: string, delimiter: string): string[] => {
+	const out: string[] = [];
+	let parent = folderParent(path, delimiter);
+	while (parent) {
+		out.push(parent);
+		parent = folderParent(parent, delimiter);
+	}
+	return out;
+};
+
+/**
+ * Puts every child straight after its parent so the list reads as a tree, while
+ * leaving the order of unrelated folders alone. A folder whose parent is absent
+ * from the list renders as a root rather than disappearing.
+ */
+export const orderFolderNodes = (
+	folders: readonly FolderTreeNode[],
+	delimiter: string,
+): FolderTreeNode[] => {
+	const present = new Set(folders.map((folder) => folder.path));
+	const emitted = new Set<string>();
+	const out: FolderTreeNode[] = [];
+
+	const emit = (folder: FolderTreeNode) => {
+		if (emitted.has(folder.path)) return;
+		emitted.add(folder.path);
+		out.push(folder);
+		for (const candidate of folders) {
+			if (folderParent(candidate.path, delimiter) === folder.path) {
+				emit(candidate);
+			}
+		}
+	};
+
+	for (const folder of folders) {
+		const parent = folderParent(folder.path, delimiter);
+		if (parent && present.has(parent)) continue;
+		emit(folder);
+	}
+	return out;
+};
+
+export const matchesQuery = (folder: FolderTreeNode, query: string): boolean =>
+	folder.label.toLowerCase().includes(query) ||
+	folder.path.toLowerCase().includes(query);
+
+/**
+ * The ancestors a query has to open for its matches to be on screen. Held apart
+ * from what the user opened by hand, so clearing the filter puts the list back
+ * the way they left it.
+ */
+export const queryExpandedPaths = (
+	folders: readonly FolderTreeNode[],
+	query: string,
+	delimiter: string,
+): Set<string> => {
+	const out = new Set<string>();
+	if (!query) return out;
+	for (const folder of folders) {
+		if (!matchesQuery(folder, query)) continue;
+		for (const ancestor of folderAncestors(folder.path, delimiter)) {
+			out.add(ancestor);
+		}
+	}
+	return out;
+};
+
+/**
+ * The rows a filtered tree shows: every match, plus the ancestors holding it on
+ * screen. Depth still comes from the path, so a match stays indented under the
+ * branch it belongs to.
+ */
+export const filterFolderTree = (
+	ordered: readonly FolderTreeNode[],
+	query: string,
+	delimiter: string,
+	expanded: ReadonlySet<string> = new Set(),
+): FolderTreeRow[] => {
+	const row = (folder: FolderTreeNode, context: boolean): FolderTreeRow => ({
+		folder,
+		depth: folderDepth(folder.path, delimiter),
+		context,
+		expanded: expanded.has(folder.path),
+	});
+	if (!query) return ordered.map((folder) => row(folder, false));
+
+	const matched = new Set<string>();
+	for (const folder of ordered) {
+		if (matchesQuery(folder, query)) matched.add(folder.path);
+	}
+	const visible = new Set(matched);
+	for (const path of matched) {
+		for (const ancestor of folderAncestors(path, delimiter)) {
+			visible.add(ancestor);
+		}
+	}
+	return ordered
+		.filter((folder) => visible.has(folder.path))
+		.map((folder) => row(folder, !matched.has(folder.path)));
+};
+
+/**
+ * The unfiltered list: roots always, and a child only while every ancestor it
+ * has on screen is open. A folder whose parent is absent from the list is a
+ * root, so it never hides behind something that was never there.
+ */
+export const collapseFolderTree = (
+	ordered: readonly FolderTreeNode[],
+	expanded: ReadonlySet<string>,
+	delimiter: string,
+): FolderTreeRow[] => {
+	const present = new Set(ordered.map((folder) => folder.path));
+	return ordered
+		.filter((folder) =>
+			folderAncestors(folder.path, delimiter).every(
+				(ancestor) => !present.has(ancestor) || expanded.has(ancestor),
+			),
+		)
+		.map((folder) => ({
+			folder,
+			depth: folderDepth(folder.path, delimiter),
+			context: false,
+			expanded: expanded.has(folder.path),
+		}));
+};
+
+/**
+ * Drops a create action at the end of every open folder's children, so "New
+ * folder" reads as the last folder inside the one you opened.
+ */
+export const withCreateRows = (
+	rows: readonly FolderTreeRow[],
+	delimiter: string,
+): FolderTreeDisplayRow[] => {
+	const out: FolderTreeDisplayRow[] = [];
+	const open: FolderTreeRow[] = [];
+
+	const closeDownTo = (path: string | null) => {
+		while (open.length > 0) {
+			const last = open[open.length - 1];
+			if (!last) break;
+			if (path?.startsWith(`${last.folder.path}${delimiter}`)) break;
+			open.pop();
+			out.push({
+				kind: "create",
+				parent: last.folder,
+				depth: last.depth + 1,
+			});
+		}
+	};
+
+	rows.forEach((row, index) => {
+		closeDownTo(row.folder.path);
+		out.push({ kind: "folder", row, index });
+		if (row.expanded) open.push(row);
+	});
+	closeDownTo(null);
+	return out;
+};