cursedbelt-core 1.0.0

package/src/core/file-tree/fileTreeModel.spec.ts

@@ -0,0 +1,462 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  descendantIdsOf,
+  type FileTreeDrop,
+  type FileTreeNode,
+  type FileTreeRow,
+  filterFileTree,
+  findFileTreeNode,
+  flattenFileTree,
+  matchTypeahead,
+  parentIdOf,
+  resolveDrop,
+  resolveKeyboardMove,
+  describeDrop,
+} from './fileTreeModel';
+
+/**
+ * The shape collections actually feeds this: albums at the top level, each one a folder,
+ * with derived folders under them. `Dinos` is locked — the server sent it, so it is drawn,
+ * but nothing may be dropped into it.
+ */
+const folder = (
+  id: string,
+  name: string,
+  children: FileTreeNode[] = [],
+  extra: Partial<FileTreeNode> = {},
+): FileTreeNode => ({ id, name, kind: 'folder', children, ...extra });
+
+const TREE: FileTreeNode[] = [
+  folder('simpsons', 'Simpsons', [
+    folder('simpsons/screencaps', 'screencaps', [
+      folder('simpsons/screencaps/s04', 's04'),
+      folder('simpsons/screencaps/s05', 's05'),
+    ]),
+    folder('simpsons/posters', 'posters'),
+  ]),
+  folder('dinos', 'Dinos', [], { acceptsDrop: false, access: 'private' }),
+  folder('travels', 'Travels', [folder('travels/iceland', 'iceland')]),
+];
+
+const rowFor = (rows: FileTreeRow[], id: string): FileTreeRow => {
+  const row = rows.find((r) => r.node.id === id);
+  if (!row) throw new Error(`no row for ${id}`);
+  return row;
+};
+
+describe('flattenFileTree', () => {
+  test('draws every row of a fully open tree, with depth and sibling index', () => {
+    const rows = flattenFileTree(TREE, []);
+    expect(rows.map((r) => r.node.id)).toEqual([
+      'simpsons',
+      'simpsons/screencaps',
+      'simpsons/screencaps/s04',
+      'simpsons/screencaps/s05',
+      'simpsons/posters',
+      'dinos',
+      'travels',
+      'travels/iceland',
+    ]);
+    expect(rowFor(rows, 'simpsons/screencaps/s04').depth).toBe(2);
+    expect(rowFor(rows, 'simpsons/posters').index).toBe(1);
+    expect(rowFor(rows, 'travels/iceland').parentId).toBe('travels');
+  });
+
+  test('🔴 `collapsed` is the exception list, so a NEW node is open, not shut', () => {
+    // The whole reason the model is inverted. A tree re-derived from the server gains nodes
+    // constantly; with an expanded-set the folder you just made would come back closed, at
+    // the exact moment its contents are what you are looking at.
+    const grown = [...TREE, folder('new', 'Just made', [folder('new/inside', 'inside')])];
+    const rows = flattenFileTree(grown, ['simpsons']);
+    expect(rows.map((r) => r.node.id)).toContain('new/inside');
+    expect(rows.map((r) => r.node.id)).not.toContain('simpsons/posters');
+  });
+
+  test('🔴 an EMPTY folder is still expandable — it gets an arrow like every other folder', () => {
+    // Owner, 2026-09-11: "Make them use an arrow icon next to a dir even when the dir is
+    // empty." The chevron says FOLDER, not OCCUPIED — VS Code's own rule — and the default
+    // used to be `children.length > 0`, which drew a brand-new folder as a leaf until
+    // something was put in it. `dinos` has no children.
+    const rows = flattenFileTree(TREE, []);
+    expect(rowFor(rows, 'dinos').expandable).toBe(true);
+    expect(rowFor(rows, 'simpsons').expandable).toBe(true);
+  });
+
+  test('an empty folder OPENS, onto nothing, and can be shut again', () => {
+    // The failure this replaces was a trap door: no twisty meant a row that had been
+    // collapsed once could never be reopened. Opening onto nothing is the honest answer.
+    const shut = flattenFileTree(TREE, ['dinos']);
+    expect(rowFor(shut, 'dinos').expanded).toBe(false);
+    const open = flattenFileTree(TREE, []);
+    expect(rowFor(open, 'dinos').expanded).toBe(true);
+    expect(open.filter((r) => r.parentId === 'dinos')).toEqual([]);
+  });
+
+  test('`expandable: false` still removes the twisty — the opt-out is kept', () => {
+    // For a row that is a folder in name and can never hold anything.
+    const rows = flattenFileTree([{ ...folder('inert', 'Inert'), expandable: false }], []);
+    expect(rowFor(rows, 'inert').expandable).toBe(false);
+  });
+
+  test('a FILE is never expandable, whatever it says', () => {
+    const rows = flattenFileTree([{ id: 'f', name: 'f.png', kind: 'file', expandable: true }], []);
+    expect(rowFor(rows, 'f').expandable).toBe(false);
+  });
+});
+
+describe('lookups', () => {
+  test('finds a node anywhere, and reports its parent', () => {
+    expect(findFileTreeNode(TREE, 'simpsons/screencaps/s05')?.name).toBe('s05');
+    expect(parentIdOf(TREE, 'simpsons/screencaps/s05')).toBe('simpsons/screencaps');
+    expect(parentIdOf(TREE, 'simpsons')).toBeNull();
+  });
+
+  test('a node the tree no longer holds reports the top level rather than throwing', () => {
+    // A refresh between the press and the release can genuinely lose the row.
+    expect(parentIdOf(TREE, 'deleted-mid-drag')).toBeNull();
+    expect(findFileTreeNode(TREE, 'deleted-mid-drag')).toBeNull();
+  });
+
+  test('descendants include the node itself — the set a drag may not enter', () => {
+    expect([...descendantIdsOf(TREE, 'simpsons/screencaps')].sort()).toEqual([
+      'simpsons/screencaps',
+      'simpsons/screencaps/s04',
+      'simpsons/screencaps/s05',
+    ]);
+  });
+});
+
+/**
+ * 🔴 The rule the whole gesture is built around: a drop that cannot happen is never
+ * OFFERED. Every case below that returns `target: null` also returns words, because a drop
+ * that is silently ignored reads as a broken app rather than a refused one.
+ */
+describe('resolveDrop', () => {
+  const rows = flattenFileTree(TREE, []);
+  const at = (id: string | null, dragId: string | null, offsetRatio = 0.5, allowReorder = false) =>
+    resolveDrop({
+      nodes: TREE,
+      row: id === null ? null : rowFor(rows, id),
+      offsetRatio,
+      dragId,
+      allowReorder,
+    });
+
+  test('a folder row takes the drop INTO it', () => {
+    expect(at('simpsons/posters', 'travels/iceland').target).toEqual({
+      kind: 'into',
+      parentId: 'simpsons/posters',
+    });
+  });
+
+  test('blank space below the tree means the top level', () => {
+    expect(at(null, 'travels/iceland').target).toEqual({ kind: 'root' });
+  });
+
+  test('🔴 a folder cannot go inside itself, and says so', () => {
+    const offer = at('simpsons/screencaps', 'simpsons/screencaps');
+    expect(offer.target).toBeNull();
+    expect(offer.refused).toBe(true);
+    expect(offer.reason).toBe('A folder cannot go inside itself');
+  });
+
+  test('🔴 nor inside one of its own folders', () => {
+    const offer = at('simpsons/screencaps/s04', 'simpsons/screencaps');
+    expect(offer.target).toBeNull();
+    expect(offer.refused).toBe(true);
+    expect(offer.reason).toBe('A folder cannot go inside one of its own folders');
+  });
+
+  test("🔴 a folder the consumer vetoed refuses with the consumer's words", () => {
+    const offer = resolveDrop({
+      nodes: TREE,
+      row: rowFor(rows, 'dinos'),
+      offsetRatio: 0.5,
+      dragId: 'travels/iceland',
+      lockedReason: 'Unlock Dinos to file things into it',
+    });
+    expect(offer.target).toBeNull();
+    expect(offer.reason).toBe('Unlock Dinos to file things into it');
+  });
+
+  test('an EXTERNAL payload (no dragId) is legal anywhere a folder accepts it', () => {
+    // Files from the desktop, or tiles from the gallery: nothing to cycle, so the only
+    // refusal left is the consumer's veto.
+    expect(at('simpsons/screencaps', null).target).toEqual({
+      kind: 'into',
+      parentId: 'simpsons/screencaps',
+    });
+    expect(at('dinos', null).refused).toBe(true);
+  });
+
+  test('a FILE row means the folder that row is in — never a wall of dead rows', () => {
+    const withFile: FileTreeNode[] = [
+      folder('a', 'A', [{ id: 'a/one.jpg', name: 'one.jpg', kind: 'file' }]),
+    ];
+    const fileRows = flattenFileTree(withFile, []);
+    const offer = resolveDrop({
+      nodes: withFile,
+      row: fileRows[1] as FileTreeRow,
+      offsetRatio: 0.5,
+      dragId: null,
+    });
+    expect(offer.target).toEqual({ kind: 'into', parentId: 'a' });
+  });
+
+  test('🔴 without allowReorder there is no between-rows target at all', () => {
+    // collections derives its folders from the paths its files carry and sorts them by
+    // name, so there is no order to change. Offering a marker would draw a promise the app
+    // cannot keep.
+    for (const ratio of [0, 0.05, 0.5, 0.95, 1]) {
+      expect(at('simpsons/posters', 'travels/iceland', ratio).target).toEqual({
+        kind: 'into',
+        parentId: 'simpsons/posters',
+      });
+    }
+  });
+
+  test('with allowReorder, the edges of a row are between and the middle is into', () => {
+    expect(at('simpsons/posters', 'travels/iceland', 0.1, true).target).toEqual({
+      kind: 'before',
+      siblingId: 'simpsons/posters',
+      parentId: 'simpsons',
+    });
+    expect(at('simpsons/posters', 'travels/iceland', 0.9, true).target).toEqual({
+      kind: 'after',
+      siblingId: 'simpsons/posters',
+      parentId: 'simpsons',
+    });
+    expect(at('simpsons/posters', 'travels/iceland', 0.5, true).target).toEqual({
+      kind: 'into',
+      parentId: 'simpsons/posters',
+    });
+  });
+});
+
+/**
+ * 🔴 The consumer's veto, which is the seam collections needs.
+ *
+ * `acceptsDrop` is a property of the TARGET alone, and collections' real rule is about the
+ * pair: its server can re-path a folder inside one album and has no route for moving one to
+ * another album, while a FILE moves between albums freely. A target-only flag cannot say
+ * that, and saying it after the drop is exactly the "marker, drop, error toast" this tree
+ * exists to avoid.
+ */
+describe('resolveDrop with a consumer veto', () => {
+  const rows = flattenFileTree(TREE, []);
+  const albumOf = (id: string) => id.split('/')[0];
+  const sameAlbum = (dragId: string | null, target: FileTreeDrop): string | null =>
+    dragId && target.kind === 'into' && albumOf(dragId) !== albumOf(target.parentId)
+      ? 'A folder cannot move to another collection'
+      : null;
+
+  test('refuses across albums, in words, before the marker is drawn', () => {
+    const offer = resolveDrop({
+      nodes: TREE,
+      row: rowFor(rows, 'travels'),
+      offsetRatio: 0.5,
+      dragId: 'simpsons/posters',
+      canDrop: sameAlbum,
+    });
+    expect(offer.target).toBeNull();
+    expect(offer.refused).toBe(true);
+    expect(offer.reason).toBe('A folder cannot move to another collection');
+  });
+
+  test('and allows the same move inside one album', () => {
+    const offer = resolveDrop({
+      nodes: TREE,
+      row: rowFor(rows, 'simpsons/screencaps'),
+      offsetRatio: 0.5,
+      dragId: 'simpsons/posters',
+      canDrop: sameAlbum,
+    });
+    expect(offer.target).toEqual({ kind: 'into', parentId: 'simpsons/screencaps' });
+  });
+
+  test('an external payload (no dragId) is never vetoed by a rule about the dragged row', () => {
+    const offer = resolveDrop({
+      nodes: TREE,
+      row: rowFor(rows, 'travels'),
+      offsetRatio: 0.5,
+      dragId: null,
+      canDrop: sameAlbum,
+    });
+    expect(offer.target).toEqual({ kind: 'into', parentId: 'travels' });
+  });
+});
+
+describe('matchTypeahead', () => {
+  const rows = flattenFileTree(TREE, []);
+  test('jumps to the next row whose name starts with what was typed', () => {
+    expect(rows[matchTypeahead(rows, 'tra', 0)]?.node.id).toBe('travels');
+    expect(rows[matchTypeahead(rows, 's0', 1)]?.node.id).toBe('simpsons/screencaps/s04');
+  });
+  test('wraps, so it does not die at the bottom of the list', () => {
+    expect(rows[matchTypeahead(rows, 'simp', rows.length - 1)]?.node.id).toBe('simpsons');
+  });
+  test('an empty query and a miss both mean "stay where you are"', () => {
+    expect(matchTypeahead(rows, '', 0)).toBe(-1);
+    expect(matchTypeahead(rows, 'zzz', 0)).toBe(-1);
+  });
+});
+
+describe('filterFileTree', () => {
+  test('keeps the folders on the way to a match', () => {
+    const found = filterFileTree(TREE, 's05');
+    expect(found.map((n) => n.id)).toEqual(['simpsons']);
+    expect(flattenFileTree(found, []).map((r) => r.node.id)).toEqual([
+      'simpsons',
+      'simpsons/screencaps',
+      'simpsons/screencaps/s05',
+    ]);
+  });
+
+  test('🔴 a folder that MATCHES keeps everything inside it', () => {
+    // Searching for a folder means you want to see what is in it — not a folder that looks
+    // empty because its children happen to spell something else.
+    const found = filterFileTree(TREE, 'screencaps');
+    expect(flattenFileTree(found, []).map((r) => r.node.id)).toEqual([
+      'simpsons',
+      'simpsons/screencaps',
+      'simpsons/screencaps/s04',
+      'simpsons/screencaps/s05',
+    ]);
+  });
+
+  test('an empty query is the whole tree, by identity', () => {
+    expect(filterFileTree(TREE, '   ')).toBe(TREE);
+  });
+});
+
+/**
+ * ⌥→ / ⌥← — the keyboard's half of the drag, and the only half touch has.
+ *
+ * 🔴 The assertions that matter are the REFUSALS. A keyboard route that can reach a
+ * destination the pointer refuses is a second, weaker opinion about what is legal, and it is
+ * the one nobody looks at because the pointer is what gets tested by hand.
+ */
+describe('resolveKeyboardMove', () => {
+  const rows = flattenFileTree(TREE, []);
+
+  test('→ demotes into the nearest FOLDER above it among its own siblings', () => {
+    // `posters` sits under `simpsons` after `screencaps`; the only unambiguous "in" is the
+    // folder immediately above it at the same level.
+    expect(
+      resolveKeyboardMove({
+        nodes: TREE,
+        rows,
+        row: rowFor(rows, 'simpsons/posters'),
+        direction: 'in',
+      }).target,
+    ).toEqual({ kind: 'into', parentId: 'simpsons/screencaps' });
+  });
+
+  test('→ with nothing above it says so rather than doing nothing', () => {
+    const offer = resolveKeyboardMove({
+      nodes: TREE,
+      rows,
+      row: rowFor(rows, 'simpsons'),
+      direction: 'in',
+    });
+    expect(offer.target).toBeNull();
+    expect(offer.reason).toBe('There is no folder above it to move into');
+  });
+
+  test('🔴 → refuses a LOCKED folder with the consumer‘s words, exactly as a drop does', () => {
+    // `dinos` is `acceptsDrop: false`. `travels` is the row after it, so `dinos` is the
+    // nearest folder above — reachable by keyboard and refused by pointer would be the bug.
+    const offer = resolveKeyboardMove({
+      nodes: TREE,
+      rows,
+      row: rowFor(rows, 'travels'),
+      direction: 'in',
+      lockedReason: 'That album is locked',
+    });
+    expect(offer.target).toBeNull();
+    expect(offer.reason).toBe('That album is locked');
+  });
+
+  test('← promotes to the folder its own folder is in', () => {
+    expect(
+      resolveKeyboardMove({
+        nodes: TREE,
+        rows,
+        row: rowFor(rows, 'simpsons/screencaps/s04'),
+        direction: 'out',
+      }).target,
+    ).toEqual({ kind: 'into', parentId: 'simpsons' });
+  });
+
+  test('← at depth 1 is the top level, and at depth 0 is a refusal with words', () => {
+    expect(
+      resolveKeyboardMove({
+        nodes: TREE,
+        rows,
+        row: rowFor(rows, 'simpsons/posters'),
+        direction: 'out',
+      }).target,
+    ).toEqual({ kind: 'root' });
+    const offer = resolveKeyboardMove({
+      nodes: TREE,
+      rows,
+      row: rowFor(rows, 'travels'),
+      direction: 'out',
+    });
+    expect(offer.target).toBeNull();
+    expect(offer.reason).toBe('It is already at the top level');
+  });
+
+  test('🔴 the consumer‘s `canDrop` gets the last word in both directions', () => {
+    const canDrop = () => 'No route for that on the server';
+    for (const direction of ['in', 'out'] as const) {
+      const offer = resolveKeyboardMove({
+        nodes: TREE,
+        rows,
+        row: rowFor(rows, 'simpsons/posters'),
+        direction,
+        canDrop,
+      });
+      expect(offer.target).toBeNull();
+      expect(offer.reason).toBe('No route for that on the server');
+    }
+  });
+
+  test('a shut folder does not hide its own SIBLINGS, so the level is still whole', () => {
+    // The visible rows are what the level is read off. `screencaps` being shut removes its
+    // children, never its peers — which is what makes reading siblings off `rows` correct.
+    const shut = flattenFileTree(TREE, ['simpsons/screencaps']);
+    expect(
+      resolveKeyboardMove({
+        nodes: TREE,
+        rows: shut,
+        row: rowFor(shut, 'simpsons/posters'),
+        direction: 'in',
+      }).target,
+    ).toEqual({ kind: 'into', parentId: 'simpsons/screencaps' });
+  });
+});
+
+describe('describeDrop', () => {
+  test('names the destination, because "where to" is the question a drag asks', () => {
+    expect(describeDrop(TREE, { kind: 'into', parentId: 'simpsons/screencaps' })).toBe(
+      'Into screencaps',
+    );
+    expect(describeDrop(TREE, { kind: 'root' })).toBe('To the top level');
+    expect(describeDrop(TREE, { kind: 'before', siblingId: 'dinos', parentId: null })).toBe(
+      'Above Dinos',
+    );
+    expect(describeDrop(TREE, { kind: 'after', siblingId: 'dinos', parentId: null })).toBe(
+      'Below Dinos',
+    );
+  });
+
+  test('🔴 no target is SILENT — a refusal has its own words and must not be doubled', () => {
+    expect(describeDrop(TREE, null)).toBe('');
+  });
+
+  test('a target the tree no longer holds still says something true', () => {
+    // The tree can be re-derived from the server between the press and the release.
+    expect(describeDrop(TREE, { kind: 'into', parentId: 'gone' })).toBe('Into this folder');
+  });
+});