Mathy Vanvoorden
ca0ba818b7
- 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.
114 lines
4.1 KiB
TypeScript
114 lines
4.1 KiB
TypeScript
/**
|
|
* 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;
|
|
}
|
|
|