cursedbelt 3.0.2 → 4.1.0

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

@@ -0,0 +1,321 @@
+/**
+ * The arithmetic of a MULTI-selection: which rows a range covers, what a ⌘-click leaves
+ * behind, which of N selected rows are the ones actually being carried, and whether a drop
+ * is legal for all of them at once — and, since 2026-09-16, where a folder made AROUND a
+ * selection goes and what it is called ({@link planWrap}).
+ *
+ * No DOM, so all of it is unit-tested in `fileTreeSelection.spec.ts` — the same split
+ * `resolveDrop`/`resolveKeyboardMove` already make against `FileTree.tsx`, and for the same
+ * reason: happy-dom computes no layout, so the pointer half of the gesture cannot be
+ * asserted anywhere and the RULES have to be reachable without it.
+ *
+ * ── Where this came from ────────────────────────────────────────────────────────────────
+ * Owner, 2026-09-14, `ideas/file-tree.md` item 2: *"If I click on a file in the sidebar file
+ * tree with the folders then hold shift and click another item in the folder, I want it to
+ * select all the files from the first file to the one I clicked next while holding shift.
+ * Then with all of those selected I want to be able to click and hold on any of them to drag
+ * and drop them to another folder or to the root outside of any folder. Another key shortcut
+ * functionality I need is selecting multiple files by holding the command key on my mac and
+ * clicking each file I want to select then dragging them to another folder. For both of these
+ * new selection functionalities I also want to be able to hold command and click delete to
+ * delete all the selected files. I also want to be able to cut and paste to move them with
+ * command + x and command + v, and copy them with command + c and command + v."*
+ *
+ * ── 🔴 Why this is here and not in `cursedbelt-core/file-tree` ───────────────────────────
+ * `fileTreeModel.ts` — `resolveDrop`, `flattenFileTree`, the node types — lives in the
+ * `cursedbelt-core` PACKAGE, which this one consumes by published version. Nothing in this
+ * repo can change that file: a `file:` or `link:` dependency is refused outright by
+ * `src/noPathDeps.spec.ts`, so the model's other half would have to be published there first
+ * and picked up here by a version bump — two packages, two publishes, for one feature.
+ *
+ * So the SPLIT the model half exists for is honoured exactly (no DOM, unit-tested, the drop
+ * rules reachable without a renderer) and the package boundary is honoured too. Everything
+ * here is built out of `fileTreeModel`'s own primitives rather than re-deriving them, so
+ * there is one definition of "legal drop" and this composes it N times.
+ */
+import {
+  type DropOffer,
+  descendantIdsOf,
+  type FileTreeNode,
+  type FileTreeRow,
+  parentIdOf,
+  type ResolveDropOptions,
+  resolveDrop,
+  walkFileTree,
+} from 'cursedbelt-core/file-tree/file-tree-model';
+
+/**
+ * Every row from the anchor to the one just clicked, inclusive — shift-click's answer.
+ *
+ * 🔴 Over the rows ON SCREEN, never over the whole tree. A shut folder between the two ends
+ * contributes its own row and none of its children, which is what Finder and VS Code both
+ * do: a range is what you can see yourself covering. Selecting rows nobody drew and then
+ * deleting them on ⌘⌫ is the version of this that loses files.
+ *
+ * `anchorId` unknown (a row the tree has since re-derived away, or nothing clicked yet)
+ * degenerates to just the clicked row rather than to the whole list — the honest reading of
+ * "from where?" when there is no where.
+ */
+export function selectionRange(
+  rows: readonly FileTreeRow[],
+  anchorId: string | null,
+  focusId: string,
+): string[] {
+  const focus = rows.findIndex((row) => row.node.id === focusId);
+  if (focus < 0) return [];
+  const anchor = anchorId === null ? -1 : rows.findIndex((row) => row.node.id === anchorId);
+  if (anchor < 0) return [focusId];
+  const from = Math.min(anchor, focus);
+  const to = Math.max(anchor, focus);
+  return rows.slice(from, to + 1).map((row) => row.node.id);
+}
+
+/**
+ * ⌘-click: in if it was out, out if it was in — and the ORDER of the rest is kept.
+ *
+ * The order is what the drag chip counts and what a consumer's own "first selected" reads,
+ * so re-sorting on every toggle would shuffle a selection under the person building it.
+ */
+export function toggleSelected(ids: readonly string[], id: string): string[] {
+  return ids.includes(id) ? ids.filter((other) => other !== id) : [...ids, id];
+}
+
+/**
+ * The selected rows with any row that is INSIDE another selected row dropped.
+ *
+ * 🔴 The trap this exists for. Shift-click a folder and the file inside it, drag both into
+ * `Archive`, and the naive answer moves the folder into `Archive` **and** the file into
+ * `Archive` — so a file that was two levels deep comes out one level deep, next to its own
+ * former parent. The person asked for one move and got their tree quietly flattened.
+ *
+ * Moving a folder moves what is in it by construction, so a descendant in the same gesture
+ * is not a second thing to move: it is the same thing, named twice. Finder resolves it the
+ * same way and says nothing about it, which is the right amount to say.
+ *
+ * Order is preserved, so this is safe to run over a selection on its way to a callback.
+ */
+export function topmostSelected(
+  nodes: readonly FileTreeNode[],
+  ids: readonly string[],
+): string[] {
+  const chosen = new Set(ids);
+  return ids.filter((id) => {
+    // `parentIdOf` answers null both at the top level and for a row this tree no longer
+    // holds, so the walk always terminates — see its own header for why the two are one
+    // answer.
+    let at = parentIdOf(nodes, id);
+    while (at !== null) {
+      if (chosen.has(at)) return false;
+      at = parentIdOf(nodes, at);
+    }
+    return true;
+  });
+}
+
+export interface ResolveMultiDropOptions extends Omit<ResolveDropOptions, 'dragId'> {
+  /**
+   * Everything being carried. Empty means an EXTERNAL payload — the same thing
+   * `resolveDrop` means by `dragId: null`.
+   */
+  dragIds: readonly string[];
+}
+
+/**
+ * Where a drag carrying N rows would land — {@link resolveDrop} asked once per row, and the
+ * strictest answer wins.
+ *
+ * 🔴 **One refusal refuses the whole drop.** A gesture that landed four of five rows and
+ * silently kept the fifth where it was is the worst possible outcome of a multi-drag: the
+ * tree looks like it obeyed, and the row that did not move is the one nobody checks. The
+ * rule the single-row drag is built around — *a drop that cannot happen is never offered* —
+ * only survives the plural if "can happen" means "for all of them".
+ *
+ * The first refusal's WORDS are what comes back, so the chip says which rule was broken
+ * rather than "some of these cannot go there".
+ *
+ * Every per-row rule is therefore honoured N times over, out of one definition: the
+ * descendant rule (a folder cannot go inside itself, and now also cannot go inside a folder
+ * being dragged beside it), `acceptsDrop`, and the consumer's `canDrop` — which is called
+ * once per dragged id, so a veto that depends on WHICH row is moving still gets asked about
+ * each one.
+ */
+export function resolveMultiDrop({ dragIds, ...rest }: ResolveMultiDropOptions): DropOffer {
+  if (dragIds.length === 0) return resolveDrop({ ...rest, dragId: null });
+  let agreed: DropOffer | null = null;
+  for (const dragId of dragIds) {
+    const offer = resolveDrop({ ...rest, dragId });
+    if (offer.refused) return offer;
+    // The target does not vary with the dragged id — only the refusals do, because the row
+    // under the pointer and the ratio are the same question for all of them. So the first
+    // non-refusing answer IS the answer; the rest of the loop is only asking permission.
+    agreed ??= offer;
+  }
+  return agreed ?? { target: null, refused: false, reason: null };
+}
+
+/**
+ * Whether a set of rows may be copied, in the consumer's words — `null` when it may.
+ *
+ * 🔴 Copy is the one clipboard verb that is NOT universal, and `apps/music` is why. A folder
+ * there is derived from the `folder` column of the tracks in it, so "copy this folder" would
+ * mean duplicating audio the owner has exactly one copy of — a gesture with no meaning, and
+ * an expensive one to offer by accident. So the tree never assumes it can paste; the app
+ * says, per row, the same shape `canDrop` already uses.
+ *
+ * The first row that refuses is the one that speaks, for the same reason as above.
+ */
+export function refuseCopy(
+  nodes: readonly FileTreeNode[],
+  ids: readonly string[],
+  canCopy: ((node: FileTreeNode) => string | null) | undefined,
+): string | null {
+  return firstRefusal(nodes, ids, canCopy);
+}
+
+/**
+ * Whether a set of rows may be WRAPPED in a new folder — `refuseCopy`'s twin, for the same
+ * reason and in the same shape.
+ *
+ * 🔴 A tree whose folders are DERIVED cannot wrap anything. `apps/music` builds its folders
+ * out of the `folder` column of the tracks in them, so "put these three into a new folder"
+ * is not a thing that host can do at all — there is no folder to make. The rule this tree is
+ * built around is *a gesture that cannot happen is never offered*, so the veto is asked
+ * BEFORE the draft row opens, never after a name has been typed into it: a refusal at commit
+ * is a refusal aimed at somebody who has already done the work.
+ *
+ * The first row that refuses is the one that speaks, as everywhere else here.
+ */
+export function refuseWrap(
+  nodes: readonly FileTreeNode[],
+  ids: readonly string[],
+  canWrap: ((node: FileTreeNode) => string | null) | undefined,
+): string | null {
+  return firstRefusal(nodes, ids, canWrap);
+}
+
+/** The shared body of the two vetoes above — one definition of "the first refusal wins". */
+function firstRefusal(
+  nodes: readonly FileTreeNode[],
+  ids: readonly string[],
+  veto: ((node: FileTreeNode) => string | null) | undefined,
+): string | null {
+  if (!veto) return null;
+  for (const id of ids) {
+    const node = nodeById(nodes, id);
+    const reason = node ? veto(node) : null;
+    if (reason) return reason;
+  }
+  return null;
+}
+
+/**
+ * A file's name with its extension taken off — the folder name a wrap opens with.
+ *
+ * `photo.jpg` → `photo`, `Notes` → `Notes`, and 🔴 `.gitignore` → `.gitignore` rather than
+ * the empty string: a name that is ALL extension has no basename to offer, and pre-filling a
+ * field with nothing is worse than pre-filling it with the name it came from. Same
+ * `lastIndexOf('.')` rule `MediaGallery`'s `extLabel` uses, so one tree and one gallery
+ * looking at the same file agree about where its name ends.
+ */
+export function wrapFolderName(name: string): string {
+  const dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(0, dot) : name;
+}
+
+/** What a wrap would do, worked out before anything is drawn or created. */
+export interface WrapPlan {
+  /**
+   * What goes into the new folder: the chosen rows, in TREE order, with any row inside
+   * another chosen row dropped (see {@link topmostSelected}) and any row this tree no longer
+   * holds forgotten.
+   */
+  ids: string[];
+  /** Where the folder is made — the parent of the first of them. `null` is the top level. */
+  parentId: string | null;
+  /** The name the field opens with: the first row's, minus its extension. */
+  name: string;
+}
+
+/**
+ * "New Folder with Selection", worked out — the whole of the gesture that is not DOM.
+ *
+ * Owner, 2026-09-13: *"allow make dir from file where dir wraps file location and gets name
+ * of file"*. Three requirements, and this function is where each of them is decided:
+ *
+ * 1. **Where the file already is.** The folder is made in the first row's OWN parent, not at
+ *    the root and not inside the selection.
+ * 2. **Named after the file**, extension dropped — {@link wrapFolderName}.
+ * 3. **The rows move into it**, which is what *wraps* means. That is `ids`, and it is handed
+ *    to the consumer in the SAME call that creates the folder — see
+ *    `FileTreeProps.onDraftCommit`.
+ *
+ * 🔴 Tree order, not click order. A selection is built by clicking, so `['b', 'a']` is an
+ * ordinary thing for a consumer to hold — and Finder names the new folder after the FIRST
+ * item, meaning the first one in the list, not the first one you happened to click.
+ *
+ * A set spread across several parents is named and placed by its first row and the rest come
+ * to it, which is the only answer to "where?" that is not arbitrary. `null` when nothing in
+ * `ids` is in the tree any more: a wrap with nothing left to wrap is a plain new folder.
+ */
+export function planWrap(
+  nodes: readonly FileTreeNode[],
+  ids: readonly string[],
+): WrapPlan | null {
+  const chosen = new Set(topmostSelected(nodes, ids));
+  const ordered = walkFileTree(nodes)
+    .filter((node) => chosen.has(node.id))
+    .map((node) => node.id);
+  const first = ordered[0];
+  if (first === undefined) return null;
+  return {
+    ids: ordered,
+    parentId: parentIdOf(nodes, first),
+    name: wrapFolderName(nodeById(nodes, first)?.name ?? ''),
+  };
+}
+
+/**
+ * The nodes behind a list of ids, in the order the ids were given, skipping any the tree no
+ * longer holds.
+ *
+ * A selection outlives a refresh — the server re-derives the tree between a ⌘-click and a
+ * ⌘⌫ and one of the rows is gone — and a callback that handed back `undefined` for it would
+ * push that case into every consumer.
+ */
+export function nodesByIds(
+  nodes: readonly FileTreeNode[],
+  ids: readonly string[],
+): FileTreeNode[] {
+  const out: FileTreeNode[] = [];
+  for (const id of ids) {
+    const node = nodeById(nodes, id);
+    if (node) out.push(node);
+  }
+  return out;
+}
+
+/** `findFileTreeNode` without the full depth-first materialisation it does per call. */
+function nodeById(nodes: readonly FileTreeNode[], id: string): FileTreeNode | null {
+  for (const node of nodes) {
+    if (node.id === id) return node;
+    const found = node.children ? nodeById(node.children, id) : null;
+    if (found) return found;
+  }
+  return null;
+}
+
+/**
+ * Everything a multi-drag has lifted off the page — the carried rows and what is under them.
+ *
+ * The single-row drag draws `data-dragged` on `descendantIdsOf(drag.id)` so a folder in the
+ * air takes its contents with it visually. With N rows that is the union, computed once per
+ * pointer move rather than per row per move.
+ */
+export function draggedIdsOf(
+  nodes: readonly FileTreeNode[],
+  ids: readonly string[],
+): Set<string> {
+  const out = new Set<string>();
+  for (const id of ids) for (const under of descendantIdsOf(nodes, id)) out.add(under);
+  return out;
+}

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

@@ -31,3 +31,24 @@ export {
   walkFileTree,
 } from 'cursedbelt-core/file-tree/file-tree-model';
 export { FileTree, type FileTreeProps } from './FileTree';
+/*
+ * The MULTI-selection half of the model — which rows a range covers, and whether a drop is
+ * legal for N dragged ids. Same split, same reason: no DOM, so it is unit-tested where the
+ * pointer gesture cannot be. It is here rather than in `cursedbelt-core` because this package
+ * consumes that one by published version and nothing in this repo may reach across — see the
+ * header of `fileTreeSelection.ts`.
+ */
+export {
+  draggedIdsOf,
+  nodesByIds,
+  planWrap,
+  refuseCopy,
+  refuseWrap,
+  type ResolveMultiDropOptions,
+  resolveMultiDrop,
+  selectionRange,
+  toggleSelected,
+  topmostSelected,
+  type WrapPlan,
+  wrapFolderName,
+} from './fileTreeSelection';

package/src/react/index.ts

@@ -384,6 +384,7 @@ export {
   type JsonEditorProps,
 } from './components/JsonEditor';
 export { Lightbox, type LightboxProps } from './components/Lightbox';
+export { ListToolbar, type ListToolbarProps } from './components/ListToolbar';
 export { Cluster, Divider, type Gap, Sidebar, Split, Stack } from './components/layout';
 export { Modal, type ModalProps, type ModalSize } from './components/Modal';
 export {

package/src/react/lib/form.ts

@@ -1,7 +1,37 @@
-import { zodResolver } from '@hookform/resolvers/zod';
-import type { DefaultValues, FieldValues, UseFormProps } from 'react-hook-form';
+import type { DefaultValues, FieldValues, Resolver, UseFormProps } from 'react-hook-form';
 import type { z } from 'zod';
 
+/**
+ * 🔴 `@hookform/resolvers` is an OPTIONAL peer, and this dynamic import is what makes it
+ * one (task 149). `cursedbelt/react` is the barrel all eight apps import; a static
+ * `import { zodResolver } from '@hookform/resolvers/zod'` at the top of this file put the
+ * package — and its own dependency tree — into every one of those installs, to serve the
+ * one function below. `src/barrelsReachNoOptionalPeer.spec.ts` is the check that keeps it
+ * out, and a `await import(...)` inside the function that needs it is the shape that spec
+ * blesses.
+ *
+ * Resolved once per process and memoized: RHF calls the resolver on every validation
+ * pass, and `zodResolver(schema)` is cheap but the module load is not.
+ */
+let zodResolverModule: Promise<typeof import('@hookform/resolvers/zod')> | undefined;
+
+const loadZodResolver = async (): Promise<typeof import('@hookform/resolvers/zod')> => {
+  zodResolverModule ??= import('@hookform/resolvers/zod');
+  try {
+    return await zodResolverModule;
+  } catch (cause) {
+    // 🔴 Loud and actionable, not an unhandled rejection three frames into RHF. A missing
+    // optional peer surfaces here as "the form never validates", which is the worst
+    // possible thing to debug without the package name in the message.
+    zodResolverModule = undefined;
+    throw new Error(
+      "cursedbelt: makeFormConfig() needs the optional peer '@hookform/resolvers' — " +
+        'run `bun add @hookform/resolvers` in the app that renders this form.',
+      { cause },
+    );
+  }
+};
+
 /**
  * The canonical react-hook-form config for every cursedbelt form (Wizard,
  * RecordPanel, modal forms). One zod schema drives validation; the validation mode
@@ -22,18 +52,31 @@ import type { z } from 'zod';
  * type Values = z.infer<typeof schema>;
  * const form = useForm<Values>(makeFormConfig(schema, { name: '', tags: [] }));
  * ```
+ *
+ * 🔴 Needs the optional peer `@hookform/resolvers` installed in the app — RHF resolvers
+ * are already async, so the load happens on the first validation rather than at import.
  */
 export function makeFormConfig<TFieldValues extends FieldValues>(
   schema: z.ZodType,
   defaults: TFieldValues,
 ): UseFormProps<TFieldValues> {
+  // Built once per form, then reused across every validation pass.
+  let resolved: Resolver<TFieldValues> | undefined;
+  const resolver: Resolver<TFieldValues> = async (values, context, options) => {
+    if (!resolved) {
+      const { zodResolver } = await loadZodResolver();
+      // zodResolver's generics don't line up with the caller's value type (the schema
+      // input/output may differ from TFieldValues); the runtime resolver is correct, so
+      // cast through the overload's param/return types rather than over-genericize.
+      resolved = zodResolver(
+        schema as Parameters<typeof zodResolver>[0],
+      ) as unknown as Resolver<TFieldValues>;
+    }
+    return resolved(values, context, options);
+  };
+
   return {
-    // zodResolver's generics don't line up with the caller's value type (the schema
-    // input/output may differ from TFieldValues); the runtime resolver is correct, so
-    // cast through the overload's param/return types rather than over-genericize.
-    resolver: zodResolver(
-      schema as Parameters<typeof zodResolver>[0],
-    ) as UseFormProps<TFieldValues>['resolver'],
+    resolver,
     defaultValues: defaults as DefaultValues<TFieldValues>,
     mode: 'onBlur',
     reValidateMode: 'onChange',

package/src/react/markdown/MarkdownDoc.spec.tsx

@@ -44,7 +44,7 @@ describe('MarkdownDoc', () => {
 
   test('javascript: and unknown-scheme links are neutralized to plain text', () => {
     const { container } = render(
-      <MarkdownDoc markdown={'[bad](javascript:alert(1)) and [weird](vbscript:x) and [ok](docs/x.md)'} />,
+      <MarkdownDoc markdown={'[bad](javascript:alert(1)) and [weird](vbscript:x) and [ok](docs/x.md)'} />, // check-doc-citations:ignore markdown fixture for the link sanitiser
     );
     const anchors = Array.from(container.querySelectorAll('a'));
     expect(anchors).toHaveLength(1);