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.

lib/keyword-nesting.ts

@@ -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;
+}
+