cursedbelt 5.34.0 → 5.35.0

package/src/react/file-tree/folderView.spec.ts

@@ -0,0 +1,174 @@
+import { describe, expect, test } from 'bun:test';
+import { type FileTreeNode, flattenFileTree } from 'cursedbelt-core/file-tree/file-tree-model';
+import {
+  applyFolderView,
+  EMPTY_FOLDER_MARKS,
+  EMPTY_FOLDER_VIEW,
+  type FolderMarks,
+  type FolderViewLocal,
+  normalizeTag,
+  parseFolderMarks,
+  parseFolderViewLocal,
+  serializeFolderMarks,
+  setHidden,
+  setTagFilter,
+  tagCounts,
+  tagHue,
+  TAG_HUES,
+  toggleFolderTag,
+} from './folderView.js';
+
+/** The rules of `folderView.ts`, with no renderer anywhere near them. */
+
+const folder = (id: string, children: FileTreeNode[] = []): FileTreeNode => ({
+  id,
+  name: id,
+  kind: 'folder',
+  children,
+});
+const file = (id: string): FileTreeNode => ({ id, name: id, kind: 'file' });
+
+//   home/            tagged home
+//     photos/
+//       a.jpg
+//   work/            tagged work
+//     dynatrace/     tagged dynatrace
+//       notes.md
+//     slides.key
+//   code/
+//     cursedforge/   tagged code
+//     scratch/
+//   readme.md        (a top-level file)
+const TREE: FileTreeNode[] = [
+  folder('home', [folder('photos', [file('a.jpg')])]),
+  folder('work', [folder('dynatrace', [file('notes.md')]), file('slides.key')]),
+  folder('code', [folder('cursedforge'), folder('scratch')]),
+  file('readme.md'),
+];
+
+const MARKS: FolderMarks = {
+  hidden: [],
+  tags: { home: ['home'], work: ['work'], dynatrace: ['dynatrace'], cursedforge: ['code'] },
+};
+
+const ids = (nodes: readonly FileTreeNode[]) => flattenFileTree(nodes, []).map((r) => r.node.id);
+const view = (local: Partial<FolderViewLocal>): FolderViewLocal => ({ ...EMPTY_FOLDER_VIEW, ...local });
+
+describe('nothing marked', () => {
+  test('hands the SAME array back — a tree with no marks pays nothing', () => {
+    const out = applyFolderView(TREE, EMPTY_FOLDER_MARKS, EMPTY_FOLDER_VIEW);
+    expect(out.nodes).toBe(TREE);
+    expect(out.hiddenCount).toBe(0);
+  });
+});
+
+describe('hiding a folder', () => {
+  const hidden: FolderMarks = { ...MARKS, hidden: ['work'] };
+
+  test('takes the folder and everything in it out of the tree', () => {
+    const out = applyFolderView(TREE, hidden, EMPTY_FOLDER_VIEW);
+    expect(ids(out.nodes)).not.toContain('work');
+    expect(ids(out.nodes)).not.toContain('notes.md');
+    expect(ids(out.nodes)).toContain('home');
+    expect(out.hiddenCount).toBe(1);
+  });
+
+  test('🔴 "show hidden" draws it back, marked `self`, and what is inside it `inherited`', () => {
+    const out = applyFolderView(TREE, hidden, view({ showHidden: true }));
+    expect(ids(out.nodes)).toEqual(ids(TREE));
+    expect(out.hiddenMarks.get('work')).toBe('self');
+    expect(out.hiddenMarks.get('dynatrace')).toBe('inherited');
+    expect(out.hiddenMarks.get('slides.key')).toBe('inherited');
+    expect(out.hiddenMarks.has('home')).toBe(false);
+  });
+
+  test('a folder hidden INSIDE a hidden folder is counted, so the menu says (2)', () => {
+    const out = applyFolderView(TREE, { ...hidden, hidden: ['work', 'dynatrace'] }, EMPTY_FOLDER_VIEW);
+    expect(out.hiddenCount).toBe(2);
+  });
+
+  test('setHidden adds once, removes, and returns the SAME value when nothing changed', () => {
+    const once = setHidden(MARKS, ['work'], true);
+    expect(setHidden(once, ['work'], true)).toBe(once);
+    expect(setHidden(once, ['work'], false).hidden).toEqual([]);
+  });
+});
+
+describe('filtering by tag (this device)', () => {
+  test('"only home + code" keeps those folders WITH their subtrees, and the path to a nested one', () => {
+    const out = applyFolderView(TREE, MARKS, view({ only: ['home', 'code'] }));
+    const shown = ids(out.nodes);
+    expect(shown).toContain('a.jpg'); // inside home: tagging a folder means what is in it too
+    expect(shown).toContain('code'); // the way to cursedforge…
+    expect(shown).toContain('cursedforge');
+    expect(shown).not.toContain('scratch'); // …pruned to just that way
+    expect(shown).not.toContain('work');
+  });
+
+  test('"only work + dynatrace" — the owner\'s second example', () => {
+    const shown = ids(applyFolderView(TREE, MARKS, view({ only: ['work', 'dynatrace'] })).nodes);
+    expect(shown).toEqual(expect.arrayContaining(['work', 'dynatrace', 'notes.md', 'slides.key']));
+    expect(shown).not.toContain('home');
+  });
+
+  test('🔴 "hide" wins over "only" — a hidden tag inside a shown one is still gone', () => {
+    const shown = ids(
+      applyFolderView(TREE, MARKS, view({ only: ['work'], hide: ['dynatrace'] })).nodes,
+    );
+    expect(shown).toContain('slides.key');
+    expect(shown).not.toContain('dynatrace');
+    expect(shown).not.toContain('notes.md');
+  });
+
+  test('a top-level file is in no folder, so a tag filter leaves it alone', () => {
+    expect(ids(applyFolderView(TREE, MARKS, view({ only: ['home'] })).nodes)).toContain('readme.md');
+  });
+
+  test('setTagFilter moves a tag between only, hide and neither — never both', () => {
+    let local = setTagFilter(EMPTY_FOLDER_VIEW, 'Home', 'only');
+    expect(local.only).toEqual(['home']);
+    local = setTagFilter(local, 'home', 'hide');
+    expect(local).toMatchObject({ only: [], hide: ['home'] });
+    expect(setTagFilter(local, 'home', null)).toMatchObject({ only: [], hide: [] });
+  });
+});
+
+describe('tags', () => {
+  test('one spelling: trimmed, collapsed, lower-cased, capped — and nothing is not a tag', () => {
+    expect(normalizeTag('  Dyna   Trace ')).toBe('dyna trace');
+    expect(normalizeTag('   ')).toBeNull();
+    expect(normalizeTag('x'.repeat(80))?.length).toBe(32);
+  });
+
+  test('toggling adds and removes; the last one off forgets the folder', () => {
+    const on = toggleFolderTag(EMPTY_FOLDER_MARKS, 'f', 'Home');
+    expect(on.tags.f).toEqual(['home']);
+    expect(toggleFolderTag(on, 'f', 'home').tags).toEqual({});
+  });
+
+  test('the tag list is derived — most used first — so an unused tag simply stops existing', () => {
+    const marks = toggleFolderTag(toggleFolderTag(MARKS, 'photos', 'home'), 'cursedforge', 'code');
+    expect(tagCounts(marks)[0]).toEqual({ tag: 'home', count: 2 });
+    expect(tagCounts(marks).some((t) => t.tag === 'code')).toBe(false);
+  });
+
+  test('a tag is always the same colour, and always one of the palette', () => {
+    expect(tagHue('home')).toBe(tagHue('home'));
+    for (const tag of ['home', 'work', 'code', 'dynatrace', 'x'])
+      expect(tagHue(tag)).toBeLessThan(TAG_HUES);
+  });
+});
+
+describe('storage', () => {
+  test('marks round-trip, and empty marks store as nothing so the key can be forgotten', () => {
+    const marks: FolderMarks = { hidden: ['a'], tags: { b: ['home'] } };
+    expect(parseFolderMarks(serializeFolderMarks(marks))).toEqual(marks);
+    expect(serializeFolderMarks(EMPTY_FOLDER_MARKS)).toBeNull();
+  });
+
+  test('🔴 a corrupt value reads as NOTHING rather than throwing — it must never cost the tree', () => {
+    expect(parseFolderMarks('{not json')).toEqual(EMPTY_FOLDER_MARKS);
+    expect(parseFolderMarks('{"hidden":"x","tags":[1]}')).toEqual({ hidden: [], tags: {} });
+    expect(parseFolderViewLocal('[]')).toEqual({ showHidden: false, only: [], hide: [] });
+  });
+});

package/src/react/file-tree/folderView.ts

@@ -0,0 +1,316 @@
+/**
+ * Hidden folders and folder tags — the arithmetic, with no DOM.
+ *
+ * Owner, 2026-09-30: *"add an option to the right click menu to hide a folder … In the menu
+ * put a show/hide hidden folders option … Add the ability for tagging folders … then being
+ * able to hide or show ones by tag or tags like just seeing folders tagged as 'home' and
+ * 'code' or 'work' and 'dynatrace' … The general hiding is persisted for all machines. Hiding
+ * or showing by tag can be stored per machine."*
+ *
+ * ── 🔴 Two stores, because the request names two scopes ─────────────────────────────────
+ *
+ *   · {@link FolderMarks} — WHAT a folder is: hidden or not, and its tags. A fact about the
+ *     folder, so it follows the person to every device (the app syncs it — see
+ *     `useFolderView`, which announces it on the preference bus like every other synced key).
+ *   · {@link FolderViewLocal} — HOW this device is looking: whether hidden folders are drawn,
+ *     and which tags it is narrowed to. *"viewing the 'home' tag at home doesn't change my
+ *     work computer"*, so this is never announced and never leaves the browser.
+ *
+ * Hiding a folder in general and filtering by tag are therefore different verbs on purpose:
+ * one is a decision about the folder, the other is a lens on the tree.
+ *
+ * ── The rules {@link applyFolderView} holds ─────────────────────────────────────────────
+ *
+ *   1. A hidden folder takes its subtree with it. With "show hidden" on, the folder is drawn
+ *      marked `self` (italic, faded) and everything under it marked `inherited` (faded only),
+ *      so the one to unhide is the one that looks different from its children.
+ *   2. "Hide tagged" wins over everything: a folder carrying a hidden tag, or inside one, is
+ *      gone — Gmail's and Linear's "is not" filter.
+ *   3. "Only tagged" keeps a tagged folder WITH its whole subtree (tagging `code` means the
+ *      code inside it too), and keeps the folders ON THE WAY to a tagged folder so it can be
+ *      reached — pruned to just that path, the way a search keeps the folders above a match.
+ *   4. Files at the top level are not in any folder and no folder verb can reach them, so a
+ *      tag filter leaves them alone. A file inside a folder follows its folder.
+ *   5. Tags are compared lower-cased and trimmed: `Home` and `home ` are one tag, the same
+ *      rule GitHub topics and Obsidian tags hold, so a typo in case never splits a filter.
+ */
+import type { FileTreeNode } from 'cursedbelt-core/file-tree/file-tree-model';
+
+/** The synced half — what each folder IS. Keyed by `FileTreeNode.id`. */
+export interface FolderMarks {
+  hidden: readonly string[];
+  tags: Readonly<Record<string, readonly string[]>>;
+}
+
+/** The per-device half — how THIS browser is looking at the tree. */
+export interface FolderViewLocal {
+  /** Draw hidden folders (marked) instead of leaving them out. Finder's ⇧⌘. */
+  showHidden: boolean;
+  /** Narrow the tree to folders carrying any of these. Empty = no narrowing. */
+  only: readonly string[];
+  /** Leave out folders carrying any of these. Wins over {@link only}. */
+  hide: readonly string[];
+}
+
+export const EMPTY_FOLDER_MARKS: FolderMarks = Object.freeze({
+  hidden: Object.freeze([]) as readonly string[],
+  tags: Object.freeze({}),
+});
+
+export const EMPTY_FOLDER_VIEW: FolderViewLocal = Object.freeze({
+  showHidden: false,
+  only: Object.freeze([]) as readonly string[],
+  hide: Object.freeze([]) as readonly string[],
+});
+
+/** Longest tag kept. A tag is a word or two; anything longer is a sentence in the wrong field. */
+export const MAX_TAG_CHARS = 32;
+
+/**
+ * The one spelling of a tag: trimmed, inner whitespace collapsed, lower-cased, capped.
+ * `null` for nothing left — the caller treats that as "no tag", never as `""`.
+ */
+export function normalizeTag(raw: string): string | null {
+  const tag = raw.trim().replace(/\s+/g, ' ').toLowerCase().slice(0, MAX_TAG_CHARS).trim();
+  return tag.length > 0 ? tag : null;
+}
+
+function uniqueTags(list: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const raw of list) {
+    const tag = typeof raw === 'string' ? normalizeTag(raw) : null;
+    if (tag && !out.includes(tag)) out.push(tag);
+  }
+  return out;
+}
+
+/**
+ * Read stored marks. Anything malformed reads as nothing rather than throwing — a corrupt
+ * value must cost the person their marks on that one value, never the tree.
+ */
+export function parseFolderMarks(raw: string | null | undefined): FolderMarks {
+  if (!raw) return EMPTY_FOLDER_MARKS;
+  try {
+    const value = JSON.parse(raw) as { hidden?: unknown; tags?: unknown };
+    const hidden = Array.isArray(value.hidden)
+      ? [...new Set(value.hidden.filter((id): id is string => typeof id === 'string' && id !== ''))]
+      : [];
+    const tags: Record<string, string[]> = {};
+    if (value.tags && typeof value.tags === 'object' && !Array.isArray(value.tags)) {
+      for (const [id, list] of Object.entries(value.tags as Record<string, unknown>)) {
+        if (!Array.isArray(list)) continue;
+        const clean = uniqueTags(list as string[]);
+        if (clean.length > 0) tags[id] = clean;
+      }
+    }
+    return { hidden, tags };
+  } catch {
+    return EMPTY_FOLDER_MARKS;
+  }
+}
+
+/** The stored form. `null` when there is nothing to keep, so an app can forget the key. */
+export function serializeFolderMarks(marks: FolderMarks): string | null {
+  const tags = Object.fromEntries(Object.entries(marks.tags).filter(([, list]) => list.length > 0));
+  if (marks.hidden.length === 0 && Object.keys(tags).length === 0) return null;
+  return JSON.stringify({ v: 1, hidden: marks.hidden, tags });
+}
+
+/** Read a device's view. Same forgiving rule as {@link parseFolderMarks}. */
+export function parseFolderViewLocal(raw: string | null | undefined): FolderViewLocal {
+  if (!raw) return EMPTY_FOLDER_VIEW;
+  try {
+    const value = JSON.parse(raw) as { showHidden?: unknown; only?: unknown; hide?: unknown };
+    return {
+      showHidden: value.showHidden === true,
+      only: Array.isArray(value.only) ? uniqueTags(value.only as string[]) : [],
+      hide: Array.isArray(value.hide) ? uniqueTags(value.hide as string[]) : [],
+    };
+  } catch {
+    return EMPTY_FOLDER_VIEW;
+  }
+}
+
+/** Hide or unhide these ids — a new value; the input is never touched. */
+export function setHidden(marks: FolderMarks, ids: readonly string[], hidden: boolean): FolderMarks {
+  const next = hidden
+    ? [...marks.hidden, ...ids.filter((id) => !marks.hidden.includes(id))]
+    : marks.hidden.filter((id) => !ids.includes(id));
+  return next.length === marks.hidden.length && next.every((id, i) => id === marks.hidden[i])
+    ? marks
+    : { ...marks, hidden: next };
+}
+
+/** Replace one folder's tags. An empty list forgets the folder entirely. */
+export function setFolderTags(marks: FolderMarks, id: string, tags: readonly string[]): FolderMarks {
+  const clean = uniqueTags(tags);
+  const { [id]: _old, ...rest } = marks.tags;
+  return { ...marks, tags: clean.length > 0 ? { ...rest, [id]: clean } : rest };
+}
+
+/** Add or take away ONE tag on one folder — the tag editor's checkbox. */
+export function toggleFolderTag(marks: FolderMarks, id: string, raw: string): FolderMarks {
+  const tag = normalizeTag(raw);
+  if (!tag) return marks;
+  const current = marks.tags[id] ?? [];
+  return setFolderTags(
+    marks,
+    id,
+    current.includes(tag) ? current.filter((t) => t !== tag) : [...current, tag],
+  );
+}
+
+/** A tag that exists, and how many folders carry it — most-used first, then by name. */
+export interface TagCount {
+  tag: string;
+  count: number;
+}
+
+/**
+ * Every tag in use. Derived, never stored: a tag no folder carries any more simply stops
+ * existing, so there is no tag list to tidy and no orphan to delete.
+ */
+export function tagCounts(marks: FolderMarks): TagCount[] {
+  const counts = new Map<string, number>();
+  for (const list of Object.values(marks.tags))
+    for (const tag of list) counts.set(tag, (counts.get(tag) ?? 0) + 1);
+  return [...counts]
+    .map(([tag, count]) => ({ tag, count }))
+    .sort((a, b) => b.count - a.count || a.tag.localeCompare(b.tag));
+}
+
+/** How many colours a tag dot can be — `--cbft-tag-0` … `--cbft-tag-7` in fileTree.css. */
+export const TAG_HUES = 8;
+
+/**
+ * A tag's colour slot, from its name — the same tag is the same colour in every app, on every
+ * device, without a colour having to be chosen or stored. FNV-1a, because it is four lines and
+ * spreads short words well.
+ */
+export function tagHue(tag: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < tag.length; i++) {
+    hash ^= tag.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0) % TAG_HUES;
+}
+
+/** Whether a device's view narrows the tree by tag at all. */
+export function tagFilterActive(local: FolderViewLocal): boolean {
+  return local.only.length > 0 || local.hide.length > 0;
+}
+
+/** Cycle one tag in the device's filter: `'only'`, `'hide'`, or `null` for neither. */
+export function setTagFilter(
+  local: FolderViewLocal,
+  raw: string,
+  mode: 'only' | 'hide' | null,
+): FolderViewLocal {
+  const tag = normalizeTag(raw);
+  if (!tag) return local;
+  const only = local.only.filter((t) => t !== tag);
+  const hide = local.hide.filter((t) => t !== tag);
+  if (mode === 'only') only.push(tag);
+  if (mode === 'hide') hide.push(tag);
+  return { ...local, only, hide };
+}
+
+/** What {@link applyFolderView} hands back. */
+export interface FolderViewResult {
+  /** The tree to draw — pruned, with new objects only where a child list changed. */
+  nodes: readonly FileTreeNode[];
+  /**
+   * Hidden rows that ARE drawn (show-hidden on): `self` for the folder that was hidden,
+   * `inherited` for everything inside it.
+   */
+  hiddenMarks: ReadonlyMap<string, 'self' | 'inherited'>;
+  /** Hidden folders the tree holds right now — the count beside "Show hidden folders". */
+  hiddenCount: number;
+}
+
+/**
+ * The tree this device should draw. See the header for the five rules.
+ *
+ * Returns the input array itself when nothing is marked and nothing is filtered, so a tree
+ * with no marks pays one check and no copy.
+ */
+export function applyFolderView(
+  nodes: readonly FileTreeNode[],
+  marks: FolderMarks,
+  local: FolderViewLocal,
+): FolderViewResult {
+  const hiddenMarks = new Map<string, 'self' | 'inherited'>();
+  const filtering = tagFilterActive(local);
+  if (marks.hidden.length === 0 && !filtering) return { nodes, hiddenMarks, hiddenCount: 0 };
+
+  const hiddenSet = new Set(marks.hidden);
+  const only = new Set(local.only);
+  const hide = new Set(local.hide);
+  let hiddenCount = 0;
+
+  const carries = (id: string, set: ReadonlySet<string>): boolean =>
+    set.size > 0 && (marks.tags[id] ?? []).some((tag) => set.has(tag));
+
+  /**
+   * `null` = drop the node. `inHidden`: an ancestor is hidden. `matched`: an ancestor
+   * carries an "only" tag (or there is no "only" filter at all).
+   */
+  const visit = (
+    node: FileTreeNode,
+    depth: number,
+    inHidden: boolean,
+    matched: boolean,
+  ): FileTreeNode | null => {
+    const selfHidden = hiddenSet.has(node.id);
+    if (selfHidden) hiddenCount++;
+    const hiddenState = selfHidden ? 'self' : inHidden ? 'inherited' : null;
+    if (hiddenState && !local.showHidden) {
+      // Still counted below it — "Show hidden folders (3)" counts nested ones too.
+      if (node.children) countHidden(node.children);
+      return null;
+    }
+    if (carries(node.id, hide)) {
+      if (node.children) countHidden(node.children);
+      return null;
+    }
+    const isMatch = matched || carries(node.id, only);
+
+    if (node.kind !== 'folder') {
+      // Rule 4: a top-level file is in no folder; a nested one follows its folder.
+      if (!isMatch && depth > 0) return null;
+      if (hiddenState) hiddenMarks.set(node.id, hiddenState);
+      return node;
+    }
+
+    let children = node.children;
+    if (node.children) {
+      const kept: FileTreeNode[] = [];
+      let changed = false;
+      for (const child of node.children) {
+        const out = visit(child, depth + 1, hiddenState !== null, isMatch);
+        if (out) kept.push(out);
+        if (out !== child) changed = true;
+      }
+      if (changed) children = kept;
+    }
+    // Rule 3: an unmatched folder survives only as the way to a matched one.
+    if (!isMatch && (!children || children.length === 0)) return null;
+    if (hiddenState) hiddenMarks.set(node.id, hiddenState);
+    return children === node.children ? node : { ...node, children: children ?? [] };
+  };
+
+  const countHidden = (list: readonly FileTreeNode[]): void => {
+    for (const node of list) {
+      if (hiddenSet.has(node.id)) hiddenCount++;
+      if (node.children) countHidden(node.children);
+    }
+  };
+
+  const out: FileTreeNode[] = [];
+  for (const node of nodes) {
+    const kept = visit(node, 0, false, only.size === 0);
+    if (kept) out.push(kept);
+  }
+  return { nodes: out, hiddenMarks, hiddenCount };
+}