cursedbelt 3.0.2 → 4.0.0

package/src/react/file-tree/fileTree.css

@@ -200,6 +200,76 @@
 	cursor: grabbing;
 }
 
+/*
+ * ── The pinned section ───────────────────────────────────────────────────────────────────
+ *
+ * Owner, 2026-09-13: *"pin open files where they stay at the top of the file tree in a new
+ * section above the folders."* It is a SIBLING of `.cbft-scroll`, not a block inside it — see
+ * the note above it in `FileTree.tsx` — so "stay at the top" is structural rather than a
+ * `position: sticky` that has to out-paint the rows it covers.
+ *
+ * 🔴 It may shrink and it may scroll, and it may never take the tree. `.cbft-scroll` is
+ * `flex: 1 1 auto` with `min-block-size: 0`, so an uncapped section of forty pins would
+ * squeeze the tree it is a shortcut INTO down to nothing — a feature that eats the thing it
+ * exists to help you reach. 40% is the cap; past it this box scrolls on its own.
+ */
+.cbft-pinned {
+	flex: 0 1 auto;
+	min-block-size: 0;
+	max-block-size: 40%;
+	display: flex;
+	flex-direction: column;
+	/* The one line that says the section ends and the tree begins. A border rather than a
+	   heavier fill: the rows inside are the same rows, and a tinted band would read as a
+	   different KIND of row rather than as the same row in a second place. */
+	border-block-end: 1px solid var(--border);
+}
+
+.cbft-pinned-list {
+	display: flex;
+	flex-direction: column;
+	/* The same 4px band `.cbft-list` takes, for the same reason. */
+	padding-block: 4px;
+	/* A plain scroller, and a scroller it must be: the section is capped above, so without
+	   this a pin past the cap is unreachable. `ScrollArea` is not usable here for the reason
+	   `.cbft-scroll` records — the tree hit-tests these boxes during a drag.
+	   guardrails-ignore no-raw-overflow: see above. */
+	overflow-y: auto;
+	overscroll-behavior: contain;
+	scrollbar-width: thin;
+	scrollbar-color: var(--cbft-scroll-thumb) transparent;
+}
+
+/*
+ * The heading. 12px is DESIGN.md §4's floor exactly, and this is the smallest thing in the
+ * component that is genuinely TEXT — a section label a person reads, not a glyph.
+ *
+ * Uppercase with tracking, which is what every sidebar section header in this design system
+ * does (and what VS Code's "OPEN EDITORS" does): it separates the label from the row names
+ * under it by shape rather than by size, so the label can stay legible without competing with
+ * the rows for weight.
+ */
+.cbft-pinned-head {
+	flex: none;
+	padding: 0.375rem var(--cbft-inset) 0.125rem;
+	font-size: 0.75rem;
+	font-weight: 600;
+	letter-spacing: 0.06em;
+	text-transform: uppercase;
+	color: var(--muted-foreground);
+}
+
+/*
+ * 🔴 A pinned copy has NO indentation guides, whatever depth its real row is at.
+ *
+ * `--cbft-depth` is 0 on every row in this section, which already blanks the repeating
+ * gradient — this states it so that a future change to the guide's arithmetic cannot bring
+ * back a line pointing at a parent that is not drawn here.
+ */
+.cbft-pinned-list .cbft-row {
+	background-image: none;
+}
+
 .cbft-empty {
 	padding: 0.75rem 0.875rem;
 	font-size: 0.8125rem;
@@ -371,6 +441,19 @@
 	opacity: 0.4;
 }
 
+/*
+ * Held by a ⌘X that has not been pasted yet — Finder's own cue, and the same language as the
+ * row in the air above, one step weaker.
+ *
+ * 🔴 It has to be VISIBLE, and this is the reason the clipboard lives in the component rather
+ * than in a prop. A cut with no mark is a keystroke that appears to have done nothing, so the
+ * next thing a person does is press it again on something else — and then ⌘V moves the wrong
+ * rows. Escape puts it down; see `FileTree.tsx`'s `clipboard`.
+ */
+.cbft-row[data-cut] {
+	opacity: 0.55;
+}
+
 /* Where it would land. A ring rather than a fill, so the row underneath stays readable. */
 .cbft-row[data-into] {
 	outline: 2px solid var(--accent-solid, var(--accent));
@@ -530,6 +613,74 @@
 	color: var(--muted-foreground);
 }
 
+/*
+ * ── The pin ──────────────────────────────────────────────────────────────────────────────
+ *
+ * 🔴 It rides in a `.cbft-tools` shelf of its own rather than inventing a fourth resting
+ * state, which is how it inherits the whole contract below in one class: 40% at rest, solid
+ * on hover / focus / selection, solid AND a 44px box on a coarse pointer, and `inTools`
+ * already stopping a press on it from selecting the row or starting a drag. A hand-rolled
+ * opacity here is exactly the drift the shelf's own header records (*"a value is copied and
+ * a rule is not"*).
+ *
+ * The glyph is 12px in the same 16px box the twisty and the type icon use, so a row with a
+ * pin is not one pixel taller than a row without one — `file-tree-geometry.json` pins the
+ * row's height to the glyph, and the pin is the third thing to go into that box.
+ */
+.cbft-pin {
+	flex: 0 0 var(--cbft-glyph);
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	inline-size: var(--cbft-glyph);
+	block-size: var(--cbft-glyph);
+	padding: 0;
+	border: 0;
+	background: none;
+	color: var(--muted-foreground);
+	cursor: pointer;
+}
+
+.cbft-pin:hover {
+	color: var(--cbft-fg);
+}
+
+/*
+ * 🔴 A PINNED row's pin is lit and never fades, in both copies.
+ *
+ * It is the only thing on the row in the folder that says *"this is also at the top"*, and a
+ * state mark that is invisible until hovered is a state nobody can scan for — the same
+ * failure the shelf's 40% floor exists to prevent, one step further. The colour is the
+ * accent, which is this tree's one strong mark and correct here for the same reason it is
+ * correct on the focus ring: it answers a different question from "where am I".
+ */
+.cbft-row[data-pinned] .cbft-pin-shelf {
+	opacity: 1;
+}
+
+.cbft-row[data-pinned] .cbft-pin {
+	color: var(--accent-solid, var(--accent));
+}
+
+/*
+ * Filled, not outlined — the one-glance difference between pinned and pinnable, and the half
+ * of it that survives for anyone who cannot see the colour change at all.
+ *
+ * 🔴 On the `<svg>` itself, not inherited from the button. The element carries `fill="none"`
+ * as a presentation attribute, and a presentation attribute on an element beats a value
+ * INHERITED from its parent — so `fill` on `.cbft-pin` would be silently ignored. Any rule
+ * targeting the svg wins, which is what this is.
+ */
+.cbft-row[data-pinned] .cbft-pin svg {
+	fill: currentColor;
+}
+
+.cbft-pin:focus-visible {
+	outline: 2px solid var(--ring, var(--accent-solid));
+	outline-offset: -2px;
+	border-radius: var(--radius-sm, 0.375rem);
+}
+
 /*
  * 🔴 Quiet, never invisible.
  *

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

@@ -0,0 +1,327 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  type FileTreeNode,
+  flattenFileTree,
+} from 'cursedbelt-core/file-tree/file-tree-model';
+import {
+  draggedIdsOf,
+  nodesByIds,
+  planWrap,
+  refuseCopy,
+  refuseWrap,
+  resolveMultiDrop,
+  selectionRange,
+  toggleSelected,
+  topmostSelected,
+  wrapFolderName,
+} from './fileTreeSelection';
+
+/**
+ * The multi-selection arithmetic, with no renderer anywhere near it.
+ *
+ * 🔴 This is the half of the feature that CAN be tested. happy-dom computes no layout, so a
+ * pointer drag in `FileTree.spec.tsx` hit-tests against zeros — which is why the drop rules
+ * for one dragged row live in `core/file-tree/fileTreeModel.spec.ts` and the rules for N live
+ * here. Asserting "a drag of three rows refuses a folder inside one of them" through a DOM
+ * would produce a test that passes on any implementation.
+ */
+
+const folder = (id: string, name: string, children: FileTreeNode[] = []): FileTreeNode => ({
+  id,
+  name,
+  kind: 'folder',
+  children,
+});
+const file = (id: string, name: string): FileTreeNode => ({ id, name, kind: 'file' });
+
+/**
+ *   Simpsons/
+ *     screencaps/
+ *       s04.png
+ *       s05.png
+ *     poster.png
+ *   Dinos/            (empty)
+ *   Travels/
+ *   loose.txt
+ */
+const TREE: FileTreeNode[] = [
+  folder('simpsons', 'Simpsons', [
+    folder('caps', 'screencaps', [file('s04', 's04.png'), file('s05', 's05.png')]),
+    file('poster', 'poster.png'),
+  ]),
+  folder('dinos', 'Dinos'),
+  folder('travels', 'Travels'),
+  file('loose', 'loose.txt'),
+];
+
+const ROWS = flattenFileTree(TREE, []);
+/** The same tree with `screencaps` shut — the case a range must not reach into. */
+const SHUT_ROWS = flattenFileTree(TREE, ['caps']);
+
+describe('selectionRange — what shift-click covers', () => {
+  test('every row from the anchor to the click, inclusive', () => {
+    expect(selectionRange(ROWS, 's04', 'travels')).toEqual(['s04', 's05', 'poster', 'dinos', 'travels']);
+  });
+
+  test('it runs the same both ways — a range has no direction', () => {
+    expect(selectionRange(ROWS, 'travels', 's04')).toEqual(selectionRange(ROWS, 's04', 'travels'));
+  });
+
+  test('an anchor that IS the click is a selection of one', () => {
+    expect(selectionRange(ROWS, 'dinos', 'dinos')).toEqual(['dinos']);
+  });
+
+  test('🔴 it covers the rows ON SCREEN, never the children of a shut folder', () => {
+    // The rule that keeps ⌘⌫ from deleting things nobody drew: a range is what you can see
+    // yourself covering. `screencaps` is shut, so its two files are not in it at all — the
+    // folder row is, because that one IS on screen.
+    expect(selectionRange(SHUT_ROWS, 'simpsons', 'dinos')).toEqual(['simpsons', 'caps', 'poster', 'dinos']);
+  });
+
+  test('no anchor yet degenerates to the clicked row, not to the whole list', () => {
+    expect(selectionRange(ROWS, null, 'dinos')).toEqual(['dinos']);
+    // Same answer for an anchor the tree has since re-derived away — the honest reading of
+    // "from where?" when there is no where.
+    expect(selectionRange(ROWS, 'deleted-since', 'dinos')).toEqual(['dinos']);
+  });
+
+  test('a click on a row that is not drawn selects nothing', () => {
+    expect(selectionRange(ROWS, 'dinos', 'ghost')).toEqual([]);
+  });
+});
+
+describe('toggleSelected — what ⌘-click leaves behind', () => {
+  test('in if it was out, out if it was in', () => {
+    expect(toggleSelected(['a'], 'b')).toEqual(['a', 'b']);
+    expect(toggleSelected(['a', 'b'], 'a')).toEqual(['b']);
+  });
+
+  test('the order of the rest survives a toggle', () => {
+    // The drag chip counts this and a consumer's "first selected" reads it, so re-sorting
+    // would shuffle a selection under the person still building it.
+    expect(toggleSelected(['c', 'a', 'b'], 'a')).toEqual(['c', 'b']);
+    expect(toggleSelected(['c', 'a'], 'b')).toEqual(['c', 'a', 'b']);
+  });
+});
+
+describe('topmostSelected — the row inside another selected row is not a second move', () => {
+  test('🔴 a selected child of a selected folder is dropped', () => {
+    // Without this, dragging `screencaps` and `s04` into `Travels` moves the folder AND the
+    // file, so a file that was two levels deep comes out one level deep beside its own former
+    // parent. The person asked for one move and got the tree flattened.
+    expect(topmostSelected(TREE, ['caps', 's04'])).toEqual(['caps']);
+  });
+
+  test('a GRANDchild too, not only a direct one', () => {
+    expect(topmostSelected(TREE, ['simpsons', 's04'])).toEqual(['simpsons']);
+  });
+
+  test('unrelated rows all survive, in the order they were given', () => {
+    expect(topmostSelected(TREE, ['travels', 'dinos', 'loose'])).toEqual(['travels', 'dinos', 'loose']);
+  });
+
+  test('a row the tree no longer holds is kept rather than silently dropped', () => {
+    // `parentIdOf` answers null for a row this tree does not contain, so the walk ends and
+    // the id passes through — the consumer is the one that knows whether it still exists.
+    expect(topmostSelected(TREE, ['ghost'])).toEqual(['ghost']);
+  });
+});
+
+describe('resolveMultiDrop — whether a drop is legal for N dragged ids', () => {
+  const rowFor = (id: string) => ROWS.find((row) => row.node.id === id) ?? null;
+
+  test('all of them may go there, so the drop is offered', () => {
+    expect(
+      resolveMultiDrop({ nodes: TREE, row: rowFor('travels'), offsetRatio: 0.5, dragIds: ['dinos', 'loose'] }),
+    ).toEqual({ target: { kind: 'into', parentId: 'travels' }, refused: false, reason: null });
+  });
+
+  test('the blank space below the tree is the top level for a whole selection', () => {
+    // *"drag and drop them to another folder or to the root outside of any folder"* — the one
+    // gesture with no target row, and it must survive the plural.
+    expect(
+      resolveMultiDrop({ nodes: TREE, row: null, offsetRatio: 0.5, dragIds: ['s04', 's05'] }),
+    ).toEqual({ target: { kind: 'root' }, refused: false, reason: null });
+  });
+
+  test('🔴 ONE refusal refuses the whole drop, and its words are what comes back', () => {
+    // The worst outcome of a multi-drag is the one that half-lands: four rows moved, the
+    // fifth silently left behind, and a tree that looks like it obeyed.
+    const offer = resolveMultiDrop({
+      nodes: TREE,
+      row: rowFor('caps'),
+      offsetRatio: 0.5,
+      dragIds: ['dinos', 'simpsons'],
+    });
+    expect(offer.refused).toBe(true);
+    expect(offer.target).toBeNull();
+    expect(offer.reason).toBe('A folder cannot go inside one of its own folders');
+  });
+
+  test('a folder dragged beside its own target refuses — not only the target itself', () => {
+    const offer = resolveMultiDrop({
+      nodes: TREE,
+      row: rowFor('dinos'),
+      offsetRatio: 0.5,
+      dragIds: ['travels', 'dinos'],
+    });
+    expect(offer.refused).toBe(true);
+    expect(offer.reason).toBe('A folder cannot go inside itself');
+  });
+
+  test("a target the consumer's `canDrop` vetoes for ANY one of them refuses for all", () => {
+    // `canDrop` is asked once per dragged id, so a veto that depends on WHICH row is moving
+    // still gets asked about each one.
+    const offer = resolveMultiDrop({
+      nodes: TREE,
+      row: rowFor('travels'),
+      offsetRatio: 0.5,
+      dragIds: ['dinos', 'loose'],
+      canDrop: (dragId) => (dragId === 'loose' ? 'That file is pinned' : null),
+    });
+    expect(offer.refused).toBe(true);
+    expect(offer.reason).toBe('That file is pinned');
+  });
+
+  test('`acceptsDrop: false` on the target refuses the set, with the consumer’s words', () => {
+    const locked: FileTreeNode[] = [
+      { id: 'vault', name: 'Vault', kind: 'folder', acceptsDrop: false, children: [] },
+      file('a', 'a.txt'),
+      file('b', 'b.txt'),
+    ];
+    const rows = flattenFileTree(locked, []);
+    const offer = resolveMultiDrop({
+      nodes: locked,
+      row: rows[0] ?? null,
+      offsetRatio: 0.5,
+      dragIds: ['a', 'b'],
+      lockedReason: 'That album is locked',
+    });
+    expect(offer).toEqual({ target: null, refused: true, reason: 'That album is locked' });
+  });
+
+  test('no dragged ids at all is an EXTERNAL payload — the same thing `dragId: null` means', () => {
+    expect(
+      resolveMultiDrop({ nodes: TREE, row: rowFor('simpsons'), offsetRatio: 0.5, dragIds: [] }),
+    ).toEqual({ target: { kind: 'into', parentId: 'simpsons' }, refused: false, reason: null });
+  });
+
+  test('a file row still means the folder that row is in, for all of them', () => {
+    expect(
+      resolveMultiDrop({ nodes: TREE, row: rowFor('poster'), offsetRatio: 0.5, dragIds: ['dinos', 'travels'] }),
+    ).toEqual({ target: { kind: 'into', parentId: 'simpsons' }, refused: false, reason: null });
+  });
+
+  test('🔴 pasting a copy back into the SAME folder is legal — the owner asked for it by name', () => {
+    // *"Copying should allow copying in another folder or the same folder."* A row's own
+    // parent is not a descendant of it, so the rule that refuses copy-into-itself leaves this
+    // alone. `s04` and `s05` live in `screencaps`.
+    expect(
+      resolveMultiDrop({ nodes: TREE, row: rowFor('caps'), offsetRatio: 0.5, dragIds: ['s04', 's05'] }),
+    ).toEqual({ target: { kind: 'into', parentId: 'caps' }, refused: false, reason: null });
+  });
+});
+
+describe('refuseCopy — the consumer’s veto on the one clipboard verb that is not universal', () => {
+  test('no veto wired means every row may be copied', () => {
+    expect(refuseCopy(TREE, ['dinos', 'loose'], undefined)).toBeNull();
+  });
+
+  test('🔴 the first row that refuses is the one that speaks', () => {
+    // `apps/music`'s folders are derived from the `folder` column of the tracks in them, so
+    // copying one would mean duplicating audio there is exactly one copy of.
+    expect(
+      refuseCopy(TREE, ['loose', 'dinos'], (node) =>
+        node.kind === 'folder' ? 'A folder here is derived, not a thing to duplicate' : null,
+      ),
+    ).toBe('A folder here is derived, not a thing to duplicate');
+  });
+
+  test('a veto that allows everything asked of it returns null', () => {
+    expect(refuseCopy(TREE, ['loose'], (node) => (node.kind === 'folder' ? 'no' : null))).toBeNull();
+  });
+});
+
+/**
+ * *"allow make dir from file where dir wraps file location and gets name of file"* — the
+ * three requirements in that sentence, one test each.
+ */
+describe('planWrap — New Folder with Selection, before any of it is drawn', () => {
+  test('🔴 the folder goes where the file IS, and is named after it without the extension', () => {
+    expect(planWrap(TREE, ['s04'])).toEqual({
+      ids: ['s04'],
+      // Not the root, and not inside the selection: `s04.png` lives in `screencaps`, so that
+      // is where the folder wrapping it is made.
+      parentId: 'caps',
+      name: 's04',
+    });
+  });
+
+  test('a top-level row wraps at the top level', () => {
+    expect(planWrap(TREE, ['loose'])?.parentId).toBeNull();
+  });
+
+  test('🔴 a multi-wrap is named after the first in TREE order, not the first clicked', () => {
+    // A selection is built by clicking, so ['s05', 's04'] is an ordinary thing to hold —
+    // and Finder names the folder after the first ITEM, which is the first in the list.
+    const plan = planWrap(TREE, ['s05', 's04']);
+    expect(plan?.name).toBe('s04');
+    expect(plan?.ids).toEqual(['s04', 's05']);
+  });
+
+  test('🔴 a row inside another chosen row is not moved twice', () => {
+    // The same rule `topmostSelected` holds for a drag: wrapping a folder wraps what is in
+    // it, so naming the child as well would flatten it out of its own parent.
+    expect(planWrap(TREE, ['caps', 's04'])?.ids).toEqual(['caps']);
+  });
+
+  test('ids the tree no longer holds are forgotten, and a wrap of nothing is null', () => {
+    expect(planWrap(TREE, ['ghost', 'loose'])?.ids).toEqual(['loose']);
+    expect(planWrap(TREE, ['ghost'])).toBeNull();
+    expect(planWrap(TREE, [])).toBeNull();
+  });
+});
+
+describe('wrapFolderName — where a name ends', () => {
+  test('the extension comes off, and a name without one is kept whole', () => {
+    expect(wrapFolderName('beach.jpg')).toBe('beach');
+    expect(wrapFolderName('2026.09.16 notes.md')).toBe('2026.09.16 notes');
+    expect(wrapFolderName('Travels')).toBe('Travels');
+  });
+
+  test('🔴 a name that is ALL extension keeps every character', () => {
+    // `.gitignore` has no basename to offer, and a field pre-filled with the empty string is
+    // worse than one pre-filled with the name it came from.
+    expect(wrapFolderName('.gitignore')).toBe('.gitignore');
+  });
+});
+
+describe('refuseWrap — the same veto shape, for a tree whose folders are derived', () => {
+  test('no veto wired means anything may be wrapped', () => {
+    expect(refuseWrap(TREE, ['loose'], undefined)).toBeNull();
+  });
+
+  test('🔴 the first row that refuses is the one that speaks', () => {
+    // `apps/music` has no folder to MAKE: its folders are derived from the tracks in them.
+    expect(
+      refuseWrap(TREE, ['loose', 'dinos'], (node) =>
+        node.kind === 'folder' ? 'Folders here are derived from the tracks' : null,
+      ),
+    ).toBe('Folders here are derived from the tracks');
+  });
+});
+
+describe('the small shared readers', () => {
+  test('nodesByIds keeps the order asked for and skips what the tree lost', () => {
+    // A selection outlives a refresh: the server re-derives the tree between a ⌘-click and a
+    // ⌘⌫ and one of the rows is gone.
+    expect(nodesByIds(TREE, ['travels', 'ghost', 's04']).map((n) => n.name)).toEqual([
+      'Travels',
+      's04.png',
+    ]);
+  });
+
+  test('draggedIdsOf is the union of what every carried row takes with it', () => {
+    expect([...draggedIdsOf(TREE, ['caps', 'dinos'])].sort()).toEqual(['caps', 'dinos', 's04', 's05']);
+  });
+});