cursedbelt 5.34.0 → 5.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/dist/react/file-tree/FileTree.d.ts +27 -1
  2. package/dist/react/file-tree/FileTree.d.ts.map +1 -1
  3. package/dist/react/file-tree/FileTree.js +183 -9
  4. package/dist/react/file-tree/FileTree.js.map +1 -1
  5. package/dist/react/file-tree/FolderViewMenus.d.ts +88 -0
  6. package/dist/react/file-tree/FolderViewMenus.d.ts.map +1 -0
  7. package/dist/react/file-tree/FolderViewMenus.js +121 -0
  8. package/dist/react/file-tree/FolderViewMenus.js.map +1 -0
  9. package/dist/react/file-tree/FolderViewPanels.d.ts +78 -0
  10. package/dist/react/file-tree/FolderViewPanels.d.ts.map +1 -0
  11. package/dist/react/file-tree/FolderViewPanels.js +155 -0
  12. package/dist/react/file-tree/FolderViewPanels.js.map +1 -0
  13. package/dist/react/file-tree/fileTree.css +146 -0
  14. package/dist/react/file-tree/folderView.d.ts +117 -0
  15. package/dist/react/file-tree/folderView.d.ts.map +1 -0
  16. package/dist/react/file-tree/folderView.js +230 -0
  17. package/dist/react/file-tree/folderView.js.map +1 -0
  18. package/dist/react/file-tree/folderViewPanels.css +217 -0
  19. package/dist/react/file-tree/index.d.ts +2 -0
  20. package/dist/react/file-tree/index.d.ts.map +1 -1
  21. package/dist/react/file-tree/index.js +9 -0
  22. package/dist/react/file-tree/index.js.map +1 -1
  23. package/dist/react/file-tree/useFolderView.d.ts +56 -0
  24. package/dist/react/file-tree/useFolderView.d.ts.map +1 -0
  25. package/dist/react/file-tree/useFolderView.js +79 -0
  26. package/dist/react/file-tree/useFolderView.js.map +1 -0
  27. package/dist/react/filter-rail/FilterRail.d.ts +7 -0
  28. package/dist/react/filter-rail/FilterRail.d.ts.map +1 -1
  29. package/dist/react/filter-rail/FilterRail.js +8 -1
  30. package/dist/react/filter-rail/FilterRail.js.map +1 -1
  31. package/dist/react/filter-rail/RailSection.d.ts +7 -1
  32. package/dist/react/filter-rail/RailSection.d.ts.map +1 -1
  33. package/dist/react/filter-rail/RailSection.js +5 -3
  34. package/dist/react/filter-rail/RailSection.js.map +1 -1
  35. package/dist/react/filter-rail/headerContextMenu.d.ts +8 -0
  36. package/dist/react/filter-rail/headerContextMenu.d.ts.map +1 -0
  37. package/dist/react/filter-rail/headerContextMenu.js +31 -0
  38. package/dist/react/filter-rail/headerContextMenu.js.map +1 -0
  39. package/dist/react/media/denseGallery.css +46 -0
  40. package/dist/react/media-gallery/rememberedPreference.d.ts +10 -1
  41. package/dist/react/media-gallery/rememberedPreference.d.ts.map +1 -1
  42. package/dist/react/media-gallery/rememberedPreference.js +12 -3
  43. package/dist/react/media-gallery/rememberedPreference.js.map +1 -1
  44. package/package.json +1 -1
  45. package/scripts/guardrails-baseline.json +1 -1
  46. package/src/react/file-tree/FileTree.tsx +323 -4
  47. package/src/react/file-tree/FolderViewMenus.tsx +242 -0
  48. package/src/react/file-tree/FolderViewPanels.tsx +402 -0
  49. package/src/react/file-tree/fileTree.css +146 -0
  50. package/src/react/file-tree/folderView.spec.ts +174 -0
  51. package/src/react/file-tree/folderView.ts +316 -0
  52. package/src/react/file-tree/folderViewPanels.css +217 -0
  53. package/src/react/file-tree/folderViewTree.spec.tsx +252 -0
  54. package/src/react/file-tree/index.ts +14 -0
  55. package/src/react/file-tree/useFolderView.ts +152 -0
  56. package/src/react/filter-rail/FilterRail.tsx +35 -6
  57. package/src/react/filter-rail/RailSection.tsx +10 -2
  58. package/src/react/filter-rail/headerContextMenu.spec.tsx +62 -0
  59. package/src/react/filter-rail/headerContextMenu.ts +37 -0
  60. package/src/react/media/denseGallery.css +46 -0
  61. package/src/react/media-gallery/rememberedPreference.ts +10 -2
@@ -195,8 +195,33 @@ import {
195
195
  topmostSelected,
196
196
  } from './fileTreeSelection.js';
197
197
  import { useInView } from '../media/previewGate.js';
198
+ import { lazyPart } from '../components/DataTable/lazyPart.js';
199
+ import { applyFolderView, tagFilterActive } from './folderView.js';
200
+ import {
201
+ type FileTreeMenuItem,
202
+ FolderViewStrip,
203
+ folderTargets,
204
+ folderViewMenuItems,
205
+ RowTagDots,
206
+ withFolderItems,
207
+ } from './FolderViewMenus.js';
208
+ import type { TreePanelProps } from './FolderViewPanels.js';
209
+ import type { FolderView, FolderViewPoint } from './useFolderView.js';
198
210
  import './fileTree.css';
199
211
 
212
+ /**
213
+ * The right-click panels — row menu, view menu, tag editor — fetched on demand. They reach
214
+ * Radix's Popover and the belt's ScrollArea, which a tree nobody right-clicks never needs, so
215
+ * they stay out of an app's first chunk; `preload` at idle makes the first right-click draw at
216
+ * once anyway. See `FolderViewPanels.tsx`.
217
+ */
218
+ const TreePanel = lazyPart<TreePanelProps>(() =>
219
+ import('./FolderViewPanels.js').then((m) => m.TreePanel),
220
+ );
221
+
222
+ /** Fetch the right-click panels now — for a spec, which must not race the chunk. */
223
+ export const preloadFileTreePanels = (): Promise<void> => TreePanel.preload();
224
+
200
225
  /** How far a press travels before it stops being a click and becomes a drag. */
201
226
  const DRAG_THRESHOLD = 4;
202
227
 
@@ -572,6 +597,29 @@ export interface FileTreeProps {
572
597
  */
573
598
  onRowMenu?: (node: FileTreeNode, at: { x: number; y: number }) => void;
574
599
 
600
+ /**
601
+ * The row's menu on **right-click** (and ⌃-click, and Shift+F10 when {@link onRowMenu} is not
602
+ * wired) — drawn by the tree at the pointer, VS Code's and Finder's gesture.
603
+ *
604
+ * Owner, 2026-09-30: *"add an option to the right click menu to hide a folder"*. Hand it the
605
+ * SAME list your ⋯ menu draws (the shape is `DropdownMenu`'s), so the two can never offer
606
+ * different things; {@link folderView}'s "Hide folder" and "Tags…" are appended to it on a
607
+ * folder. Omit both and a right-click is the browser's, as it always was.
608
+ */
609
+ rowMenu?: (node: FileTreeNode) => readonly FileTreeMenuItem[];
610
+ /**
611
+ * Items for the right-click on the BLANK space under the rows — "New folder", say. Drawn above
612
+ * {@link folderView}'s own view items in the same menu.
613
+ */
614
+ backgroundMenu?: () => readonly FileTreeMenuItem[];
615
+ /**
616
+ * Hidden folders and folder tags — `useFolderView({ key })`. Wiring it is what puts "Hide
617
+ * folder" and "Tags…" on a folder's right-click, "Show hidden folders" and "Filter by tag" on
618
+ * the blank space's, ⇧⌘. on the keyboard, the tag dots on tagged rows and the strip that says
619
+ * when this device is narrowing the tree. See `folderView.ts` for the rules.
620
+ */
621
+ folderView?: FolderView | null;
622
+
575
623
  /** Trailing controls for a row — the tool shelf. Quiet at rest, never invisible. */
576
624
  renderTools?: (node: FileTreeNode) => ReactNode;
577
625
  /** Leading glyph. Defaults to a folder/file mark. */
@@ -788,6 +836,9 @@ export function FileTree({
788
836
  onWrapStart,
789
837
  canWrap,
790
838
  onRowMenu,
839
+ rowMenu,
840
+ backgroundMenu,
841
+ folderView = null,
791
842
  renderTools,
792
843
  renderIcon,
793
844
  thumbnailTransform,
@@ -974,7 +1025,28 @@ export function FileTree({
974
1025
  if (!clipboard) mirrored.current = null;
975
1026
  }, [clipboard]);
976
1027
 
977
- const shown = useMemo(() => (filter ? filterFileTree(nodes, filter) : nodes), [nodes, filter]);
1028
+ /*
1029
+ * Hidden folders and the tag filter come off FIRST, before the search: a search that found
1030
+ * things inside a hidden folder would be the folder un-hiding itself. See `folderView.ts`.
1031
+ */
1032
+ const viewed = useMemo(
1033
+ () => (folderView ? applyFolderView(nodes, folderView.marks, folderView.local) : null),
1034
+ [nodes, folderView],
1035
+ );
1036
+ const viewedNodes = viewed?.nodes ?? nodes;
1037
+ const shown = useMemo(
1038
+ () => (filter ? filterFileTree(viewedNodes, filter) : viewedNodes),
1039
+ [viewedNodes, filter],
1040
+ );
1041
+ /**
1042
+ * What the pinned section is built from — the tree WITHOUT the folder view. A pin is the
1043
+ * person saying *"keep it there until I unpin it"*, and hiding the folder it lives in, or
1044
+ * narrowing this device to another tag, is not unpinning it.
1045
+ */
1046
+ const pinSource = useMemo(
1047
+ () => (viewed ? (filter ? filterFileTree(nodes, filter) : nodes) : shown),
1048
+ [viewed, filter, nodes, shown],
1049
+ );
978
1050
  /*
979
1051
  * A search shows everything it kept — a match hidden inside a collapsed folder is a match
980
1052
  * the person cannot see, which reads as "not found".
@@ -1004,14 +1076,14 @@ export function FileTree({
1004
1076
  */
1005
1077
  const pinnedRows = useMemo<FileTreeRow[]>(() => {
1006
1078
  if (pinned.length === 0) return [];
1007
- const all = new Map(flattenFileTree(shown, []).map((row) => [row.node.id, row]));
1079
+ const all = new Map(flattenFileTree(pinSource, []).map((row) => [row.node.id, row]));
1008
1080
  const out: FileTreeRow[] = [];
1009
1081
  for (const id of pinned) {
1010
1082
  const real = all.get(id);
1011
1083
  if (real) out.push({ ...real, depth: 0, expandable: false, expanded: false });
1012
1084
  }
1013
1085
  return out;
1014
- }, [pinned, shown]);
1086
+ }, [pinned, pinSource]);
1015
1087
 
1016
1088
  /**
1017
1089
  * The whole selection, singular or plural — `[selectedId]` for a consumer that never
@@ -1658,6 +1730,89 @@ export function FileTree({
1658
1730
  [rowEl],
1659
1731
  );
1660
1732
 
1733
+ // ── Right-click menus ─────────────────────────────────────────────────────────────────
1734
+
1735
+ /**
1736
+ * The row menu open at the pointer, or the view menu when the tree owns it alone (no
1737
+ * {@link FileTreeProps.folderView}, whose hook holds the view menu so the APP's header can
1738
+ * open it too).
1739
+ */
1740
+ const [ctxMenu, setCtxMenu] = useState<
1741
+ | { kind: 'row'; node: FileTreeNode; pinned: boolean; at: FolderViewPoint }
1742
+ | { kind: 'view'; at: FolderViewPoint }
1743
+ | null
1744
+ >(null);
1745
+
1746
+ /** Whether a row has a right-click menu at all — otherwise the browser's stays. */
1747
+ const hasRowMenu = useCallback(
1748
+ (node: FileTreeNode) => Boolean(rowMenu) || (folderView !== null && node.kind === 'folder'),
1749
+ [rowMenu, folderView],
1750
+ );
1751
+
1752
+ const openRowMenu = useCallback(
1753
+ (node: FileTreeNode, pinnedCopy: boolean, at: FolderViewPoint) => {
1754
+ setFocused({ id: node.id, pinned: pinnedCopy });
1755
+ setCtxMenu({ kind: 'row', node, pinned: pinnedCopy, at });
1756
+ },
1757
+ [],
1758
+ );
1759
+
1760
+ const openViewMenu = useCallback(
1761
+ (at: FolderViewPoint) => {
1762
+ if (folderView) folderView.openViewMenu(at);
1763
+ else setCtxMenu({ kind: 'view', at });
1764
+ },
1765
+ [folderView],
1766
+ );
1767
+
1768
+ /*
1769
+ * The blank space under the rows answers a right-click with the VIEW menu. A native listener
1770
+ * rather than a JSX one because the scroller is the tree's frame, not a control — giving it a
1771
+ * role to hang a handler on would announce it as one. A row answers its own menu; a press on
1772
+ * a row's tools, or on a row with no menu, keeps the browser's.
1773
+ */
1774
+ const wantsBlankMenu = Boolean(folderView || backgroundMenu);
1775
+ useEffect(() => {
1776
+ const scroller = scrollRef.current;
1777
+ if (!scroller || !wantsBlankMenu) return;
1778
+ const onContextMenu = (event: MouseEvent) => {
1779
+ if (event.target instanceof Element && event.target.closest('.cbft-row')) return;
1780
+ event.preventDefault();
1781
+ openViewMenu({ x: event.clientX, y: event.clientY });
1782
+ };
1783
+ scroller.addEventListener('contextmenu', onContextMenu);
1784
+ return () => scroller.removeEventListener('contextmenu', onContextMenu);
1785
+ }, [wantsBlankMenu, openViewMenu]);
1786
+
1787
+ /** Fetch the panels once the page is idle, if this tree has any menu to open. */
1788
+ const hasMenus = wantsBlankMenu || Boolean(rowMenu);
1789
+ useEffect(() => {
1790
+ if (!hasMenus) return;
1791
+ const load = () => void TreePanel.preload().catch(() => {});
1792
+ const idle = globalThis.requestIdleCallback;
1793
+ if (idle) {
1794
+ const handle = idle(load, { timeout: 4000 });
1795
+ return () => globalThis.cancelIdleCallback?.(handle);
1796
+ }
1797
+ const timer = setTimeout(load, 1500);
1798
+ return () => clearTimeout(timer);
1799
+ }, [hasMenus]);
1800
+
1801
+ /**
1802
+ * Put the keyboard back on the row a menu was opened from — but only if the menu left it on
1803
+ * `<body>`. An item that opened ANOTHER panel (Tags…) has already moved focus into it, and
1804
+ * taking it back would leave the person typing into nothing.
1805
+ */
1806
+ const refocusAfterMenu = useCallback(
1807
+ (id: string, pinnedCopy: boolean) => {
1808
+ requestAnimationFrame(() => {
1809
+ const at = globalThis.document?.activeElement;
1810
+ if (!at || at === globalThis.document.body) rowEl(id, pinnedCopy)?.focus();
1811
+ });
1812
+ },
1813
+ [rowEl],
1814
+ );
1815
+
1661
1816
  /*
1662
1817
  * ── The keyboard comes back from a rename ─────────────────────────────────────────────
1663
1818
  *
@@ -1762,6 +1917,29 @@ export function FileTree({
1762
1917
  onRowMenu(row.node, { x: box?.right ?? 0, y: box?.bottom ?? 0 });
1763
1918
  return;
1764
1919
  }
1920
+ // No menu of the consumer's own: the tree's right-click menu answers the same keys.
1921
+ if (
1922
+ hasRowMenu(row.node) &&
1923
+ (event.key === 'ContextMenu' || (event.shiftKey && event.key === 'F10'))
1924
+ ) {
1925
+ event.preventDefault();
1926
+ const box = rowEl(row.node.id, pinnedCopy)?.getBoundingClientRect();
1927
+ openRowMenu(row.node, pinnedCopy, {
1928
+ x: (box?.left ?? 0) + 24,
1929
+ y: box?.bottom ?? 0,
1930
+ });
1931
+ return;
1932
+ }
1933
+ /*
1934
+ * ⇧⌘. — show or leave out hidden folders. Finder's own chord for hidden files, so a Mac
1935
+ * user already has it in their hands. By `code`: with Shift held, `key` is `>` on a US
1936
+ * keyboard and something else on others.
1937
+ */
1938
+ if (folderView && event.code === 'Period' && event.shiftKey && (event.metaKey || event.ctrlKey)) {
1939
+ event.preventDefault();
1940
+ folderView.setShowHidden(!folderView.local.showHidden);
1941
+ return;
1942
+ }
1765
1943
 
1766
1944
  /*
1767
1945
  * ── ⌃⌘T — pin, and unpin ────────────────────────────────────────────────────────
@@ -2095,6 +2273,9 @@ export function FileTree({
2095
2273
  onPinnedChange,
2096
2274
  onRenameStart,
2097
2275
  onRowMenu,
2276
+ hasRowMenu,
2277
+ openRowMenu,
2278
+ folderView,
2098
2279
  onSelect,
2099
2280
  onWrapStart,
2100
2281
  mirror,
@@ -2461,6 +2642,15 @@ export function FileTree({
2461
2642
  data-access={node.access && node.access !== 'normal' ? node.access : undefined}
2462
2643
  /* A hit in a search the consumer ran — see `FileTreeNode.matched`. */
2463
2644
  data-matched={node.matched || undefined}
2645
+ /* Drawn although hidden — "Show hidden folders" is on. `self` is the folder that was
2646
+ hidden (italic and faded), `inherited` is what is inside it (faded only), so the
2647
+ one to unhide is the one that looks different. See `.cbft-row[data-hidden]`. */
2648
+ data-hidden={viewed?.hiddenMarks.get(node.id)}
2649
+ /* Its right-click menu is open — Finder's ring round the row it was opened on. */
2650
+ data-menu-open={
2651
+ (ctxMenu?.kind === 'row' && ctxMenu.node.id === node.id && ctxMenu.pinned === pinnedCopy) ||
2652
+ undefined
2653
+ }
2464
2654
  style={{ '--cbft-depth': row.depth } as React.CSSProperties}
2465
2655
  onPointerDown={(event) => {
2466
2656
  if (inTools(event.target)) return;
@@ -2484,6 +2674,12 @@ export function FileTree({
2484
2674
  }}
2485
2675
  onKeyDown={(event) => onKeyDown(event, row, list, pinnedCopy)}
2486
2676
  onFocus={() => setFocused({ id: node.id, pinned: pinnedCopy })}
2677
+ onContextMenu={(event) => {
2678
+ if (inTools(event.target) || !hasRowMenu(node)) return;
2679
+ event.preventDefault();
2680
+ event.stopPropagation();
2681
+ openRowMenu(node, pinnedCopy, { x: event.clientX, y: event.clientY });
2682
+ }}
2487
2683
  {...externalHandlers(node)}
2488
2684
  >
2489
2685
  {row.expandable ? (
@@ -2609,6 +2805,34 @@ export function FileTree({
2609
2805
  */}
2610
2806
  {/* The mark's words are the consumer's when it has its own privacy
2611
2807
  vocabulary — see accessMarkCopy for why the defaults are collections'. */}
2808
+ {/* The folder that was hidden, drawn because "Show hidden folders" is on: an eye-off
2809
+ after the name, so the row reads as HIDDEN rather than as private (which is
2810
+ italic too). Not on the rows inside it — those are only faded. */}
2811
+ {viewed?.hiddenMarks.get(node.id) === 'self' ? (
2812
+ <span className='cbft-hidden-mark' role='img' aria-label='Hidden'>
2813
+ {/* Lucide's `eye-off`, drawn for the reason the chevron and the pin are. */}
2814
+ <svg
2815
+ viewBox='0 0 24 24'
2816
+ width='12'
2817
+ height='12'
2818
+ fill='none'
2819
+ stroke='currentColor'
2820
+ strokeWidth='2'
2821
+ strokeLinecap='round'
2822
+ strokeLinejoin='round'
2823
+ focusable='false'
2824
+ aria-hidden='true'
2825
+ >
2826
+ <path d='M10.73 5.08A10.43 10.43 0 0 1 12 5c7 0 10 7 10 7a13.16 13.16 0 0 1-1.67 2.68' />
2827
+ <path d='M6.61 6.61A13.53 13.53 0 0 0 2 12s3 7 10 7a9.74 9.74 0 0 0 5.39-1.61' />
2828
+ <path d='M14.12 14.12a3 3 0 1 1-4.24-4.24' />
2829
+ <path d='m2 2 20 20' />
2830
+ </svg>
2831
+ </span>
2832
+ ) : null}
2833
+ {folderView && node.kind === 'folder' ? (
2834
+ <RowTagDots tags={folderView.marks.tags[node.id] ?? []} />
2835
+ ) : null}
2612
2836
  {node.access === 'private' || node.access === 'locked' ? (
2613
2837
  <Tooltip content={accessMarkCopy(node.access, accessCopy)}>
2614
2838
  {/* Not `aria-hidden`: this is the one thing on the row a screen reader
@@ -2751,6 +2975,91 @@ export function FileTree({
2751
2975
  );
2752
2976
  };
2753
2977
 
2978
+ /** The open right-click menu or tag editor, if any — see `FolderViewMenus.tsx`. */
2979
+ const treeMenus = (): ReactNode => {
2980
+ const out: ReactNode[] = [];
2981
+ if (ctxMenu?.kind === 'row') {
2982
+ const { node, pinned: pinnedCopy, at } = ctxMenu;
2983
+ const close = () => {
2984
+ setCtxMenu(null);
2985
+ refocusAfterMenu(node.id, pinnedCopy);
2986
+ };
2987
+ const own = rowMenu?.(node) ?? [];
2988
+ const ids = folderTargets(
2989
+ node,
2990
+ selection,
2991
+ (id) => findFileTreeNode(nodes, id)?.kind === 'folder',
2992
+ );
2993
+ const fv = folderView
2994
+ ? folderViewMenuItems(folderView, node, ids, viewed?.hiddenMarks.get(node.id) ?? null)
2995
+ : [];
2996
+ const items = withFolderItems(own, fv);
2997
+ if (items.length > 0)
2998
+ out.push(
2999
+ <TreePanel
3000
+ key='row-menu'
3001
+ kind='row'
3002
+ at={at}
3003
+ label={`Actions for ${node.name}`}
3004
+ items={items}
3005
+ onClose={close}
3006
+ />,
3007
+ );
3008
+ }
3009
+ const viewAt =
3010
+ folderView?.panel?.kind === 'view'
3011
+ ? folderView.panel.at
3012
+ : ctxMenu?.kind === 'view'
3013
+ ? ctxMenu.at
3014
+ : null;
3015
+ if (viewAt) {
3016
+ const close = () => {
3017
+ setCtxMenu(null);
3018
+ folderView?.closePanel();
3019
+ };
3020
+ const folderIds = flattenFileTree(shown, [])
3021
+ .filter((r) => r.expandable)
3022
+ .map((r) => r.node.id);
3023
+ out.push(
3024
+ <TreePanel
3025
+ key='view-menu'
3026
+ kind='view'
3027
+ view={folderView}
3028
+ at={viewAt}
3029
+ hiddenCount={viewed?.hiddenCount ?? 0}
3030
+ extraItems={backgroundMenu?.() ?? []}
3031
+ onCollapseAll={folderIds.length > 0 ? () => shutFolders(folderIds) : null}
3032
+ onClose={close}
3033
+ />,
3034
+ );
3035
+ }
3036
+ if (folderView?.panel?.kind === 'tags') {
3037
+ const { ids } = folderView.panel;
3038
+ const names = ids.map((id) => findFileTreeNode(nodes, id)?.name ?? '').filter(Boolean);
3039
+ let at = folderView.panel.at;
3040
+ if (!at) {
3041
+ // Opened from a ⋯ menu, which has no pointer to give: under the first folder's row.
3042
+ const box = (rowEl(ids[0] ?? '', false) ?? rootRef.current)?.getBoundingClientRect();
3043
+ at = { x: (box?.left ?? 0) + 24, y: box?.bottom ?? 0 };
3044
+ }
3045
+ out.push(
3046
+ <TreePanel
3047
+ key={`tags:${ids.join(',')}`}
3048
+ kind='tags'
3049
+ view={folderView}
3050
+ ids={ids}
3051
+ names={names.length > 0 ? names : ['this folder']}
3052
+ at={at}
3053
+ onClose={() => {
3054
+ folderView.closePanel();
3055
+ if (ids[0]) refocusAfterMenu(ids[0], false);
3056
+ }}
3057
+ />,
3058
+ );
3059
+ }
3060
+ return out;
3061
+ };
3062
+
2754
3063
  return (
2755
3064
  <div
2756
3065
  ref={rootRef}
@@ -2759,6 +3068,7 @@ export function FileTree({
2759
3068
  /* See `markPath` — the path is still marked in the DOM, only not painted. */
2760
3069
  data-quiet-path={markPath ? undefined : true}
2761
3070
  >
3071
+ {folderView ? <FolderViewStrip view={folderView} onOpenMenu={openViewMenu} /> : null}
2762
3072
  {/*
2763
3073
  * ── The pinned section — above the folders, and outside the scroller ─────────────
2764
3074
  *
@@ -2817,7 +3127,15 @@ export function FileTree({
2817
3127
  {...(onSelectionChange ? { 'aria-multiselectable': true } : {})}
2818
3128
  className={`cbft-list${drag?.active ? ' cbft-list-dragging' : ''}`}
2819
3129
  >
2820
- {rows.length === 0 && !draft ? <div className='cbft-empty'>{empty}</div> : null}
3130
+ {rows.length === 0 && !draft ? (
3131
+ <div className='cbft-empty'>
3132
+ {/* Empty BECAUSE of this device's tag filter is a different sentence from empty —
3133
+ "nothing here" would read as the folders having been deleted. */}
3134
+ {folderView && tagFilterActive(folderView.local) && nodes.length > 0
3135
+ ? 'No folders carry these tags. Right-click here to change the filter.'
3136
+ : empty}
3137
+ </div>
3138
+ ) : null}
2821
3139
 
2822
3140
  {/*
2823
3141
  * 🔴 A draft with no parent belongs at the TOP, not the bottom.
@@ -2871,6 +3189,7 @@ export function FileTree({
2871
3189
  </span>
2872
3190
  </div>
2873
3191
  ) : null}
3192
+ {treeMenus()}
2874
3193
  {/* The same words, for a screen reader, which cannot see the chip — and, between drags,
2875
3194
  whatever the last keyboard move said. See `notice`. */}
2876
3195
  <span className='cbft-sr' role='status' aria-live='polite'>
@@ -0,0 +1,242 @@
1
+ /**
2
+ * The file tree's hidden-folder and folder-tag pieces that draw WITHOUT a right-click — the
3
+ * menu item lists, the tag dots and the active-filter strip. The panels a right-click opens
4
+ * (menus, tag editor, tag filter) are `FolderViewPanels.tsx`, loaded on demand: they reach
5
+ * Radix's Popover and the belt's ScrollArea, ~5 kB gzip that a tree nobody right-clicks never
6
+ * needs — measured on collections' first chunk, 2026-09-30, when this was one module.
7
+ *
8
+ * The arithmetic is `folderView.ts`, the storage is `useFolderView.ts`, and `FileTree.tsx`
9
+ * decides when each of these opens. Kept out of that file because it is already the largest
10
+ * in the package, and because none of this is part of the drag gesture it is organised around.
11
+ *
12
+ * ── What was copied, and from whom ──────────────────────────────────────────────────────
13
+ *
14
+ * · **Right-click a row** → the row's own menu, at the pointer: VS Code's explorer and
15
+ * Finder. The same item list the app's ⋯ menu draws, so the two cannot drift.
16
+ * · **Right-click the blank space or the header** → a VIEW menu: VS Code's explorer header
17
+ * menu and Finder's View menu. *Show hidden folders* carries Finder's ⇧⌘. chord, because a
18
+ * Mac user already knows it.
19
+ * · **Tag editor** → Gmail's *Label as*: one field that both FINDS a tag and CREATES one,
20
+ * with a checklist under it. Finder's tag popover is the same shape. A tag is created by
21
+ * using it, never in a separate "manage tags" screen, and stops existing when no folder
22
+ * carries it — so there is nothing to tidy.
23
+ * · **Filter by tag** → Linear's and Gmail's *is* / *is not*, as two quiet toggles per tag
24
+ * ("Only", "Hide"), labelled **This device** because that is the one thing about it a
25
+ * person could not guess.
26
+ * · **The strip** → Linear's filter bar: when the tree is narrowed, the tree SAYS so, with
27
+ * a one-click way back. A folder missing on one machine and present on another is
28
+ * otherwise indistinguishable from a folder that was deleted.
29
+ */
30
+ import type { ReactNode } from 'react';
31
+ import type { FileTreeNode } from 'cursedbelt-core/file-tree/file-tree-model';
32
+ import { Tooltip } from '../components/Tooltip.js';
33
+ import { UnstyledButton } from '../components/UnstyledButton.js';
34
+ import { tagFilterActive, tagHue } from './folderView.js';
35
+ import type { FolderView, FolderViewPoint } from './useFolderView.js';
36
+
37
+ /**
38
+ * One entry in a tree menu. The SAME shape `DropdownMenu` takes (`DropdownMenuItem`), so an
39
+ * app hands one list to its ⋯ menu and to {@link FileTreeProps.rowMenu} and the right-click
40
+ * and the ⋯ can never offer different things. `shortcut` is drawn only here.
41
+ */
42
+ export type FileTreeMenuItem =
43
+ | {
44
+ key: string;
45
+ label: ReactNode;
46
+ /** A second, muted line — the folder's tags under "Tags…". */
47
+ description?: ReactNode;
48
+ /** Hover text; on a disabled item, the reason it cannot work. */
49
+ title?: string;
50
+ disabled?: boolean;
51
+ destructive?: boolean;
52
+ /** Present = a toggle, drawn with a tick when true. */
53
+ checked?: boolean;
54
+ shortcut?: string;
55
+ onClick?: () => void;
56
+ divider?: false;
57
+ }
58
+ | { key: string; divider: true; label?: ReactNode };
59
+
60
+ /** Which folders a folder verb aimed at `node` acts on — the selection if it is in one. */
61
+ export function folderTargets(
62
+ node: FileTreeNode,
63
+ selection: readonly string[],
64
+ isFolder: (id: string) => boolean,
65
+ ): string[] {
66
+ if (selection.length > 1 && selection.includes(node.id)) {
67
+ const folders = selection.filter(isFolder);
68
+ if (folders.length > 0) return folders;
69
+ }
70
+ return [node.id];
71
+ }
72
+
73
+ /**
74
+ * "Hide folder" and "Tags…" for a folder — the row's half of the feature, as menu items.
75
+ *
76
+ * Exported so an app's own ⋯ menu offers exactly what the right-click does: spread it into
77
+ * the list you hand `DropdownMenu`. `ids` is the folders it acts on (see {@link folderTargets});
78
+ * `hiddenState` is what the tree drew the row as.
79
+ */
80
+ export function folderViewMenuItems(
81
+ view: FolderView,
82
+ node: FileTreeNode,
83
+ ids: readonly string[] = [node.id],
84
+ hiddenState: 'self' | 'inherited' | null = view.marks.hidden.includes(node.id) ? 'self' : null,
85
+ ): FileTreeMenuItem[] {
86
+ if (node.kind !== 'folder') return [];
87
+ const many = ids.length > 1;
88
+ const what = many ? `${ids.length} folders` : `“${node.name}”`;
89
+ const items: FileTreeMenuItem[] = [];
90
+ if (hiddenState === 'self') {
91
+ items.push({
92
+ key: 'fv-unhide',
93
+ label: many ? `Unhide ${ids.length} folders` : 'Unhide folder',
94
+ title: `Show ${what} in the tree again, on every device`,
95
+ onClick: () => view.unhide(ids),
96
+ });
97
+ } else if (hiddenState === 'inherited') {
98
+ items.push({
99
+ key: 'fv-unhide',
100
+ label: 'Unhide folder',
101
+ disabled: true,
102
+ title: 'It is inside a hidden folder — unhide that folder to bring this one back',
103
+ });
104
+ } else {
105
+ items.push({
106
+ key: 'fv-hide',
107
+ label: many ? `Hide ${ids.length} folders` : 'Hide folder',
108
+ title: `Leave ${what} out of the tree on every device. “Show hidden folders” (⇧⌘.) brings it back.`,
109
+ onClick: () => view.hide(ids),
110
+ });
111
+ }
112
+ const current = view.marks.tags[node.id] ?? [];
113
+ items.push({
114
+ key: 'fv-tags',
115
+ label: 'Tags…',
116
+ ...(current.length > 0 && !many ? { description: current.join(', ') } : {}),
117
+ title: `Tag ${what} — then show or hide folders by tag from the tree's own menu`,
118
+ onClick: () => view.openTagEditor(ids),
119
+ });
120
+ return items;
121
+ }
122
+
123
+ /**
124
+ * An app's row items with the folder items placed among them: ABOVE a trailing destructive
125
+ * group (Finder and VS Code keep Delete last, under a rule), otherwise after everything.
126
+ */
127
+ export function withFolderItems(
128
+ own: readonly FileTreeMenuItem[],
129
+ folder: readonly FileTreeMenuItem[],
130
+ ): FileTreeMenuItem[] {
131
+ if (folder.length === 0) return [...own];
132
+ if (own.length === 0) return [...folder];
133
+ const firstDanger = own.findIndex((item) => !item.divider && item.destructive);
134
+ const rule = firstDanger > 0 && own[firstDanger - 1]?.divider ? firstDanger - 1 : -1;
135
+ if (rule < 0) return [...own, { key: 'fv-sep-row', divider: true }, ...folder];
136
+ return [
137
+ ...own.slice(0, rule),
138
+ { key: 'fv-sep-row', divider: true },
139
+ ...folder,
140
+ ...own.slice(rule),
141
+ ];
142
+ }
143
+
144
+ /** The colour mark for one tag. */
145
+ export function TagDot({ tag }: { tag: string }): ReactNode {
146
+ return <span className='cbft-tagdot' data-hue={tagHue(tag)} aria-hidden='true' />;
147
+ }
148
+
149
+ /** A row's tags, as up to three dots after its name — Finder's tag dots. */
150
+ export function RowTagDots({ tags }: { tags: readonly string[] }): ReactNode {
151
+ if (tags.length === 0) return null;
152
+ const words = tags.join(', ');
153
+ return (
154
+ <Tooltip content={`Tags: ${words}`}>
155
+ <span className='cbft-tagdots' role='img' aria-label={`Tags: ${words}`}>
156
+ {tags.slice(0, 3).map((tag) => (
157
+ <TagDot key={tag} tag={tag} />
158
+ ))}
159
+ </span>
160
+ </Tooltip>
161
+ );
162
+ }
163
+
164
+ /**
165
+ * The strip above the rows while this device is narrowing the tree — what is filtered, and
166
+ * one press to undo it. Drawn only while something is in force.
167
+ */
168
+ export function FolderViewStrip({
169
+ view,
170
+ onOpenMenu,
171
+ }: {
172
+ view: FolderView;
173
+ onOpenMenu: (at: FolderViewPoint) => void;
174
+ }): ReactNode {
175
+ const { local } = view;
176
+ if (!local.showHidden && !tagFilterActive(local)) return null;
177
+ const parts: ReactNode[] = [];
178
+ if (local.only.length > 0)
179
+ parts.push(
180
+ <span key='only' className='cbft-fv-part'>
181
+ Only{' '}
182
+ {local.only.map((tag) => (
183
+ <span key={tag} className='cbft-fv-chip'>
184
+ <TagDot tag={tag} />
185
+ {tag}
186
+ </span>
187
+ ))}
188
+ </span>,
189
+ );
190
+ if (local.hide.length > 0)
191
+ parts.push(
192
+ <span key='hide' className='cbft-fv-part'>
193
+ Hiding{' '}
194
+ {local.hide.map((tag) => (
195
+ <span key={tag} className='cbft-fv-chip'>
196
+ <TagDot tag={tag} />
197
+ {tag}
198
+ </span>
199
+ ))}
200
+ </span>,
201
+ );
202
+ if (local.showHidden) parts.push(<span key='hidden' className='cbft-fv-part'>Showing hidden</span>);
203
+
204
+ const open = (event: React.MouseEvent) => {
205
+ event.preventDefault();
206
+ const box = event.currentTarget.getBoundingClientRect();
207
+ onOpenMenu(
208
+ event.type === 'contextmenu' ? { x: event.clientX, y: event.clientY } : { x: box.left, y: box.bottom },
209
+ );
210
+ };
211
+
212
+ return (
213
+ <div
214
+ className='cbft-fv-strip'
215
+ role='toolbar'
216
+ aria-label="This device's folder filter"
217
+ onContextMenu={open}
218
+ >
219
+ <UnstyledButton
220
+ className='cbft-fv-strip-open'
221
+ tooltip='Change what this device shows'
222
+ onClick={open}
223
+ >
224
+ {parts}
225
+ </UnstyledButton>
226
+ <UnstyledButton
227
+ className='cbft-fv-strip-clear'
228
+ tooltip={
229
+ local.showHidden && !tagFilterActive(local)
230
+ ? 'Leave hidden folders out again'
231
+ : 'Show every folder again'
232
+ }
233
+ onClick={() => {
234
+ if (tagFilterActive(local)) view.clearTagFilter();
235
+ else view.setShowHidden(false);
236
+ }}
237
+ >
238
+ {tagFilterActive(local) ? 'Clear' : 'Hide'}
239
+ </UnstyledButton>
240
+ </div>
241
+ );
242
+ }