feat: Add nesting of tags in a tree
- levels are joined by forward slashes in the keywords - behaviour is opt-in for now - long paths are shortened if there is not enough display room Closes #687.
This commit is contained in:
Mathy Vanvoorden
@@ -0,0 +1,115 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { formatKeyword, formatKeywordLabels, keywordRenderings } from "@/lib/keyword-format";
|
||||
import type { KeywordDefinition } from "@/stores/settings-store";
|
||||
|
||||
const kw = (id: string, label: string): KeywordDefinition => ({ id, label, color: "blue" });
|
||||
|
||||
// Work
|
||||
// Clients
|
||||
// Acme
|
||||
// Personal
|
||||
const KEYWORDS: KeywordDefinition[] = [
|
||||
kw("work", "Work"),
|
||||
kw("work/clients", "Clients"),
|
||||
kw("work/clients/acme", "Acme"),
|
||||
kw("work/personal", "Personal"),
|
||||
];
|
||||
|
||||
describe("formatKeyword with nesting on", () => {
|
||||
it("joins the display name of every level", () => {
|
||||
expect(formatKeyword("work/clients/acme", KEYWORDS, true)).toBe("Work/Clients/Acme");
|
||||
});
|
||||
|
||||
it("returns the plain display name for a tag with one level", () => {
|
||||
expect(formatKeyword("work", KEYWORDS, true)).toBe("Work");
|
||||
});
|
||||
|
||||
it("falls back to the raw level for one this client does not know", () => {
|
||||
expect(formatKeyword("work/archive/2026", KEYWORDS, true)).toBe("Work/archive/2026");
|
||||
expect(formatKeyword("unknown", [], true)).toBe("unknown");
|
||||
});
|
||||
});
|
||||
|
||||
describe("formatKeyword with nesting off", () => {
|
||||
it("names a tag by its own label, leaving a slash in the id uninterpreted", () => {
|
||||
// The setting says a slash means nothing, so an id that happens to contain
|
||||
// one - from before it was turned off, or from another client - is a single
|
||||
// opaque token rather than a hierarchy.
|
||||
expect(formatKeyword("work/clients/acme", KEYWORDS, false)).toBe("Acme");
|
||||
expect(formatKeyword("work", KEYWORDS, false)).toBe("Work");
|
||||
});
|
||||
|
||||
it("falls back to the whole id when the tag has no definition", () => {
|
||||
expect(formatKeyword("work/archive/2026", KEYWORDS, false)).toBe("work/archive/2026");
|
||||
});
|
||||
|
||||
it("offers no shortening, leaving the markup to clip", () => {
|
||||
expect(keywordRenderings(formatKeywordLabels("work/clients/acme", KEYWORDS, false)))
|
||||
.toEqual(["Acme"]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("keywordRenderings", () => {
|
||||
it("shortens by one intermediate level at a time, outermost first", () => {
|
||||
expect(keywordRenderings(["Work", "Clients", "Acme", "EU", "Sales"])).toEqual([
|
||||
"Work/Clients/Acme/EU/Sales",
|
||||
"Work/../Acme/EU/Sales",
|
||||
"Work/.../EU/Sales",
|
||||
"Work/.../Sales",
|
||||
]);
|
||||
});
|
||||
|
||||
it("collapses to a single ... as soon as the run covers more than one level", () => {
|
||||
expect(keywordRenderings(["Work", "Clients", "Acme", "Sales"])).toEqual([
|
||||
"Work/Clients/Acme/Sales",
|
||||
"Work/../Acme/Sales",
|
||||
"Work/.../Sales",
|
||||
]);
|
||||
});
|
||||
|
||||
it("uses .. for a lone intermediate level, never ...", () => {
|
||||
expect(keywordRenderings(["Work", "Clients", "Acme"])).toEqual([
|
||||
"Work/Clients/Acme",
|
||||
"Work/../Acme",
|
||||
]);
|
||||
});
|
||||
|
||||
it("has nothing to shorten without an intermediate level", () => {
|
||||
expect(keywordRenderings(["Work", "Acme"])).toEqual(["Work/Acme"]);
|
||||
expect(keywordRenderings(["Work"])).toEqual(["Work"]);
|
||||
});
|
||||
|
||||
it("drops a rendering that would not come out shorter", () => {
|
||||
// "../" costs as much as the level it replaces, so shortening buys nothing.
|
||||
expect(keywordRenderings(["a", "it", "b"])).toEqual(["a/it/b"]);
|
||||
expect(keywordRenderings(["a", "x", "b"])).toEqual(["a/x/b"]);
|
||||
});
|
||||
});
|
||||
|
||||
// How the components use the two together: resolve a tag to its display names,
|
||||
// then hand the ladder to `useShortenedText` to pick a rung.
|
||||
describe("keywordRenderings over formatKeywordLabels", () => {
|
||||
it("shortens a display name by the same ladder as an id", () => {
|
||||
const deep: KeywordDefinition[] = [
|
||||
kw("work", "Work"),
|
||||
kw("work/clients", "Clients"),
|
||||
kw("work/clients/acme", "Acme"),
|
||||
kw("work/clients/acme/eu", "Europe"),
|
||||
];
|
||||
|
||||
expect(keywordRenderings(formatKeywordLabels("work/clients/acme/eu", deep, true))).toEqual([
|
||||
"Work/Clients/Acme/Europe",
|
||||
"Work/../Acme/Europe",
|
||||
"Work/.../Europe",
|
||||
]);
|
||||
});
|
||||
|
||||
it("treats a slash inside one display name as part of that name, not a level", () => {
|
||||
const slashed: KeywordDefinition[] = [kw("work", "Work"), kw("work/acme-r-d", "Acme/R&D")];
|
||||
|
||||
// Two levels, so there is no intermediate level to shorten.
|
||||
expect(keywordRenderings(formatKeywordLabels("work/acme-r-d", slashed, true))).toEqual([
|
||||
"Work/Acme/R&D",
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,138 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
MAX_KEYWORD_ID_LENGTH,
|
||||
buildKeywordTree,
|
||||
composeKeywordId,
|
||||
getParentKeywordId,
|
||||
hasChildKeywords,
|
||||
isKeywordDescendant,
|
||||
keywordLevels,
|
||||
normalizeKeywordLevel,
|
||||
} from "@/lib/keyword-nesting";
|
||||
import type { KeywordDefinition } from "@/stores/settings-store";
|
||||
|
||||
const kw = (id: string, label: string): KeywordDefinition => ({ id, label, color: "blue" });
|
||||
|
||||
// Work
|
||||
// Clients
|
||||
// Acme
|
||||
// Personal
|
||||
const KEYWORDS: KeywordDefinition[] = [
|
||||
kw("work", "Work"),
|
||||
kw("work/clients", "Clients"),
|
||||
kw("work/clients/acme", "Acme"),
|
||||
kw("work/personal", "Personal"),
|
||||
];
|
||||
|
||||
describe("normalizeKeywordLevel", () => {
|
||||
it("lowercases and folds unsupported characters into single dashes", () => {
|
||||
expect(normalizeKeywordLevel("My Custom Tag!")).toBe("my-custom-tag");
|
||||
expect(normalizeKeywordLevel(" Spaced Out ")).toBe("spaced-out");
|
||||
expect(normalizeKeywordLevel("--Trimmed--")).toBe("trimmed");
|
||||
});
|
||||
|
||||
it("treats a slash as part of the name, not as a level", () => {
|
||||
expect(normalizeKeywordLevel("Acme/R&D")).toBe("acme-r-d");
|
||||
});
|
||||
|
||||
it("returns an empty string when nothing usable is left", () => {
|
||||
expect(normalizeKeywordLevel(" ")).toBe("");
|
||||
expect(normalizeKeywordLevel("!!!")).toBe("");
|
||||
});
|
||||
});
|
||||
|
||||
describe("composeKeywordId", () => {
|
||||
it("returns a bare slug at the top level", () => {
|
||||
expect(composeKeywordId(null, "Work")).toBe("work");
|
||||
expect(composeKeywordId("", "Work")).toBe("work");
|
||||
});
|
||||
|
||||
it("appends the slug below the parent", () => {
|
||||
expect(composeKeywordId("work/clients", "Acme")).toBe("work/clients/acme");
|
||||
});
|
||||
|
||||
it("never produces a trailing separator for an unusable name", () => {
|
||||
expect(composeKeywordId("work", "!!!")).toBe("");
|
||||
});
|
||||
});
|
||||
|
||||
describe("keywordLevels", () => {
|
||||
it("splits an id into its levels", () => {
|
||||
expect(keywordLevels("work/clients/acme")).toEqual(["work", "clients", "acme"]);
|
||||
expect(keywordLevels("work")).toEqual(["work"]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("getParentKeywordId", () => {
|
||||
it("drops the last level", () => {
|
||||
expect(getParentKeywordId("work/clients/acme")).toBe("work/clients");
|
||||
});
|
||||
|
||||
it("returns null for a top-level tag", () => {
|
||||
expect(getParentKeywordId("work")).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("isKeywordDescendant", () => {
|
||||
it("matches anything below the ancestor", () => {
|
||||
expect(isKeywordDescendant("work/clients/acme", "work")).toBe(true);
|
||||
expect(isKeywordDescendant("work/clients", "work")).toBe(true);
|
||||
});
|
||||
|
||||
it("does not match the ancestor itself or a shared name prefix", () => {
|
||||
expect(isKeywordDescendant("work", "work")).toBe(false);
|
||||
expect(isKeywordDescendant("workshop/tools", "work")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("hasChildKeywords", () => {
|
||||
it("reports whether any defined tag sits below the given one", () => {
|
||||
expect(hasChildKeywords("work", KEYWORDS)).toBe(true);
|
||||
expect(hasChildKeywords("work/clients", KEYWORDS)).toBe(true);
|
||||
expect(hasChildKeywords("work/clients/acme", KEYWORDS)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("MAX_KEYWORD_ID_LENGTH", () => {
|
||||
it("leaves room for the `$label:` prefix within the 255-character keyword limit", () => {
|
||||
expect(MAX_KEYWORD_ID_LENGTH).toBe(248);
|
||||
expect("$label:".length + MAX_KEYWORD_ID_LENGTH).toBe(255);
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildKeywordTree", () => {
|
||||
it("nests each tag under its parent and records the depth", () => {
|
||||
const [work] = buildKeywordTree(KEYWORDS);
|
||||
|
||||
expect(work.id).toBe("work");
|
||||
expect(work.depth).toBe(0);
|
||||
expect(work.children.map((c) => c.id)).toEqual(["work/clients", "work/personal"]);
|
||||
|
||||
const clients = work.children[0];
|
||||
expect(clients.depth).toBe(1);
|
||||
expect(clients.children.map((c) => c.id)).toEqual(["work/clients/acme"]);
|
||||
expect(clients.children[0].depth).toBe(2);
|
||||
});
|
||||
|
||||
it("keeps the manual order within a level", () => {
|
||||
const reordered = [KEYWORDS[0], KEYWORDS[3], KEYWORDS[1], KEYWORDS[2]];
|
||||
const [work] = buildKeywordTree(reordered);
|
||||
|
||||
expect(work.children.map((c) => c.id)).toEqual(["work/personal", "work/clients"]);
|
||||
});
|
||||
|
||||
it("keeps a tag whose parent is not defined at the root", () => {
|
||||
const orphan = buildKeywordTree([kw("work/clients/acme", "Acme")]);
|
||||
|
||||
expect(orphan).toHaveLength(1);
|
||||
expect(orphan[0].id).toBe("work/clients/acme");
|
||||
expect(orphan[0].depth).toBe(0);
|
||||
});
|
||||
|
||||
it("returns every tag as a root when no id describes a hierarchy", () => {
|
||||
const flat = buildKeywordTree([kw("red", "Red"), kw("blue", "Blue")]);
|
||||
|
||||
expect(flat.map((n) => n.id)).toEqual(["red", "blue"]);
|
||||
expect(flat.every((n) => n.depth === 0 && n.children.length === 0)).toBe(true);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,83 @@
|
||||
/**
|
||||
* Naming a tag on screen.
|
||||
*
|
||||
* A nested tag is written out level by level - `Work/Clients/Acme` - and a flat
|
||||
* one is simply its own name, so nothing here asks the caller which kind it
|
||||
* has. `keywordRenderings` additionally offers progressively shorter forms for
|
||||
* a name with nowhere to fit, which `useShortenedText` measures against the
|
||||
* room actually available.
|
||||
*/
|
||||
import type { KeywordDefinition } from "@/stores/settings-store";
|
||||
import { KEYWORD_SEPARATOR, keywordLevels } from "./keyword-nesting";
|
||||
|
||||
/** Stands in for one level left out of a name. */
|
||||
export const KEYWORD_SHORTENED_LEVEL = "..";
|
||||
|
||||
/** Stands in for a run of more than one level left out of a name. */
|
||||
export const KEYWORD_SHORTENED_RUN = "...";
|
||||
|
||||
/**
|
||||
* The display name of a tag, one entry per level, outermost first. A tag with
|
||||
* one level yields a single entry, so callers need not care either way.
|
||||
*
|
||||
* `nested` is the user's setting. With nesting off a slash carries no meaning,
|
||||
* so the id is one opaque token and the tag is named by its own label - nobody
|
||||
* who left the setting alone should find their tags rewritten because an id
|
||||
* happens to contain a slash, which can outlast turning nesting off, or arrive
|
||||
* through settings sync or another client.
|
||||
*
|
||||
* With nesting on, each level resolves to that tag's display name, falling back
|
||||
* to the raw level of the id when it has no definition - the settings list only
|
||||
* describes the tags this client knows about. Levels stay separate entries
|
||||
* because a display name may itself contain a slash, which is part of that one
|
||||
* name rather than a level of its own.
|
||||
*/
|
||||
export function formatKeywordLabels(
|
||||
id: string,
|
||||
keywords: KeywordDefinition[],
|
||||
nested: boolean,
|
||||
): string[] {
|
||||
const label = (levelId: string) => keywords.find((keyword) => keyword.id === levelId)?.label;
|
||||
if (!nested) return [label(id) ?? id];
|
||||
|
||||
const levels = keywordLevels(id);
|
||||
return levels.map((level, index) =>
|
||||
label(levels.slice(0, index + 1).join(KEYWORD_SEPARATOR)) ?? level,
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* The display name of a tag: `Work/Clients/Acme` for a nested one, its own name
|
||||
* otherwise. The general way to name a tag on screen.
|
||||
*/
|
||||
export function formatKeyword(
|
||||
id: string,
|
||||
keywords: KeywordDefinition[],
|
||||
nested: boolean,
|
||||
): string {
|
||||
return formatKeywordLabels(id, keywords, nested).join(KEYWORD_SEPARATOR);
|
||||
}
|
||||
|
||||
/**
|
||||
* Every way a name can be written, longest first: in full, then with an ever
|
||||
* longer run of intermediate levels replaced by `..`, collapsing to a single
|
||||
* `...` as soon as that run covers more than one level.
|
||||
*
|
||||
* The outermost and innermost levels always survive - between them they say
|
||||
* which branch a tag belongs to and which tag it is, which is exactly what a
|
||||
* trailing ellipsis destroys. A rendering that would not actually come out
|
||||
* shorter than the one before it (levels named `it`, say) is dropped, so
|
||||
* walking the list never makes the text grow.
|
||||
*/
|
||||
export function keywordRenderings(levels: string[]): string[] {
|
||||
const renderings = [levels.join(KEYWORD_SEPARATOR)];
|
||||
for (let shortened = 1; shortened <= levels.length - 2; shortened++) {
|
||||
const marker = shortened === 1 ? KEYWORD_SHORTENED_LEVEL : KEYWORD_SHORTENED_RUN;
|
||||
const rendering = [levels[0], marker, ...levels.slice(shortened + 1)]
|
||||
.join(KEYWORD_SEPARATOR);
|
||||
if (rendering.length < renderings[renderings.length - 1].length) {
|
||||
renderings.push(rendering);
|
||||
}
|
||||
}
|
||||
return renderings;
|
||||
}
|
||||
@@ -0,0 +1,113 @@
|
||||
/**
|
||||
* Tag nesting.
|
||||
*
|
||||
* A tag is stored on the server as the JMAP keyword `$label:<id>`, where `id`
|
||||
* is a slug derived from the display name. Nesting reuses that single id: the
|
||||
* levels are joined with a forward slash, so `$label:work/clients` is the child
|
||||
* of `$label:work`. Keeping the hierarchy inside the id means the server stays
|
||||
* the source of truth for tag membership and existing lookups by keyword keep
|
||||
* working.
|
||||
*
|
||||
* RFC 8621 section 4.1.1 allows a keyword of 1-255 characters from the ASCII
|
||||
* range %x21-%x7e minus `( ) { ] % * " \`, so the separator is legal but the
|
||||
* length of a deep id is not free - `MAX_KEYWORD_ID_LENGTH` is the budget a
|
||||
* composed id has to stay within.
|
||||
*
|
||||
* Turning any of this into text for the screen lives in `keyword-format`.
|
||||
*/
|
||||
import type { KeywordDefinition } from "@/stores/settings-store";
|
||||
import { KEYWORD_PREFIX } from "./thread-utils";
|
||||
|
||||
/** Separates parent from child inside a tag id. */
|
||||
export const KEYWORD_SEPARATOR = "/";
|
||||
|
||||
/** Longest keyword a JMAP server has to accept (RFC 8621, section 4.1.1). */
|
||||
export const MAX_KEYWORD_LENGTH = 255;
|
||||
|
||||
/** What is left for the id once the `$label:` prefix is spent. */
|
||||
export const MAX_KEYWORD_ID_LENGTH = MAX_KEYWORD_LENGTH - KEYWORD_PREFIX.length;
|
||||
|
||||
/** A tag definition placed in the hierarchy its id describes. */
|
||||
export interface KeywordNode extends KeywordDefinition {
|
||||
children: KeywordNode[];
|
||||
depth: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reduces a display name to one level of an id: lowercase, and everything
|
||||
* outside `[a-z0-9_-]` folded to a single dash. The separator is not exempt -
|
||||
* a slash typed into the name is a literal part of that name, not a level.
|
||||
* The only slug function for tag ids; keep it the only one.
|
||||
*/
|
||||
export function normalizeKeywordLevel(name: string): string {
|
||||
return name
|
||||
.trim()
|
||||
.toLowerCase()
|
||||
.replace(/[^a-z0-9_-]/g, "-")
|
||||
.replace(/-+/g, "-")
|
||||
.replace(/^-|-$/g, "");
|
||||
}
|
||||
|
||||
/** Builds the id a tag named `name` gets under `parentId` (null = top level). */
|
||||
export function composeKeywordId(parentId: string | null, name: string): string {
|
||||
const level = normalizeKeywordLevel(name);
|
||||
if (!parentId || !level) return level;
|
||||
return `${parentId}${KEYWORD_SEPARATOR}${level}`;
|
||||
}
|
||||
|
||||
/** Splits `work/clients/acme` into `["work", "clients", "acme"]`. */
|
||||
export function keywordLevels(id: string): string[] {
|
||||
return id.split(KEYWORD_SEPARATOR).filter(Boolean);
|
||||
}
|
||||
|
||||
/** The id of the tag one level up, or null for a top-level tag. */
|
||||
export function getParentKeywordId(id: string): string | null {
|
||||
const index = id.lastIndexOf(KEYWORD_SEPARATOR);
|
||||
return index === -1 ? null : id.slice(0, index);
|
||||
}
|
||||
|
||||
/** True when `candidateId` sits anywhere below `ancestorId`. */
|
||||
export function isKeywordDescendant(candidateId: string, ancestorId: string): boolean {
|
||||
return candidateId.startsWith(`${ancestorId}${KEYWORD_SEPARATOR}`);
|
||||
}
|
||||
|
||||
/** True when any defined tag sits below `id`. */
|
||||
export function hasChildKeywords(id: string, keywords: KeywordDefinition[]): boolean {
|
||||
return keywords.some((keyword) => isKeywordDescendant(keyword.id, id));
|
||||
}
|
||||
|
||||
/**
|
||||
* Arranges tag definitions into the tree their ids describe, preserving the
|
||||
* user's manual order within each level.
|
||||
*
|
||||
* A tag whose direct parent is not defined stays at the root rather than being
|
||||
* hidden or grafted onto a grandparent; callers name such a root in full so the
|
||||
* missing level is still visible.
|
||||
*/
|
||||
export function buildKeywordTree(keywords: KeywordDefinition[]): KeywordNode[] {
|
||||
const nodes = new Map<string, KeywordNode>();
|
||||
for (const keyword of keywords) {
|
||||
nodes.set(keyword.id, { ...keyword, children: [], depth: 0 });
|
||||
}
|
||||
|
||||
const roots: KeywordNode[] = [];
|
||||
for (const keyword of keywords) {
|
||||
const node = nodes.get(keyword.id)!;
|
||||
const parentId = getParentKeywordId(keyword.id);
|
||||
const parent = parentId ? nodes.get(parentId) : undefined;
|
||||
if (parent) {
|
||||
parent.children.push(node);
|
||||
} else {
|
||||
roots.push(node);
|
||||
}
|
||||
}
|
||||
|
||||
const setDepth = (node: KeywordNode, depth: number) => {
|
||||
node.depth = depth;
|
||||
node.children.forEach((child) => setDepth(child, depth + 1));
|
||||
};
|
||||
roots.forEach((root) => setDepth(root, 0));
|
||||
|
||||
return roots;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user