@djangocfg/ui-tools 2.1.315 → 2.1.317

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.315",
+  "version": "2.1.317",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -75,9 +75,14 @@
       "require": "./src/tools/CodeEditor/index.ts"
     },
     "./tree": {
-      "types": "./src/tools/Tree/index.tsx",
-      "import": "./src/tools/Tree/index.tsx",
-      "require": "./src/tools/Tree/index.tsx"
+      "types": "./dist/tree/index.d.ts",
+      "import": "./dist/tree/index.mjs",
+      "require": "./dist/tree/index.cjs"
+    },
+    "./file-icon": {
+      "types": "./dist/file-icon/index.d.ts",
+      "import": "./dist/file-icon/index.mjs",
+      "require": "./dist/file-icon/index.cjs"
     },
     "./styles": "./src/styles/index.css",
     "./dist.css": "./dist/index.css"
@@ -96,8 +101,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.315",
-    "@djangocfg/ui-core": "^2.1.315",
+    "@djangocfg/i18n": "^2.1.317",
+    "@djangocfg/ui-core": "^2.1.317",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -146,13 +151,14 @@
   },
   "optionalDependencies": {
     "@mapbox/mapbox-gl-draw": "^1.4.3",
-    "@maplibre/maplibre-gl-geocoder": "^1.7.0"
+    "@maplibre/maplibre-gl-geocoder": "^1.7.0",
+    "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.315",
+    "@djangocfg/i18n": "^2.1.317",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.315",
-    "@djangocfg/ui-core": "^2.1.315",
+    "@djangocfg/typescript-config": "^2.1.317",
+    "@djangocfg/ui-core": "^2.1.317",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/FileIcon/FileIcon.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { File as FileFallback, Folder, FolderOpen } from 'lucide-react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { getMaterialIconsSync, loadMaterialIcons } from './loader';
+
+export type FileIconSize = 12 | 14 | 16 | 18 | 20 | 24 | 28 | 32 | 40 | 48 | 64;
+
+export interface FileIconProps {
+  /** File name (with extension) or folder name. */
+  name: string;
+  /** Render a folder icon instead of a file icon. */
+  isFolder?: boolean;
+  /** Folder open / closed state. Ignored when `isFolder` is false. */
+  isExpanded?: boolean;
+  /** Pixel size of the icon. */
+  size?: FileIconSize;
+  className?: string;
+}
+
+/**
+ * VSCode-style file icon.
+ *
+ * - Folders render Lucide `Folder` / `FolderOpen` (amber tint).
+ * - Files use `material-file-icons` if it's installed in the consumer; otherwise
+ *   fall back to a neutral Lucide `File` icon.
+ *
+ * The optional dependency is loaded lazily on first render — there is zero
+ * bundle cost for consumers who never mount this component.
+ */
+export function FileIcon({
+  name,
+  isFolder = false,
+  isExpanded = false,
+  size = 16,
+  className,
+}: FileIconProps) {
+  const [svg, setSvg] = useState<string | null>(() => {
+    if (isFolder) return null;
+    const fn = getMaterialIconsSync();
+    return fn ? (fn(name)?.svg ?? null) : null;
+  });
+
+  useEffect(() => {
+    if (isFolder) {
+      setSvg(null);
+      return;
+    }
+    let cancelled = false;
+    void loadMaterialIcons().then((fn) => {
+      if (cancelled) return;
+      setSvg(fn ? (fn(name)?.svg ?? null) : null);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [isFolder, name]);
+
+  if (isFolder) {
+    const Icon = isExpanded ? FolderOpen : Folder;
+    return (
+      <Icon
+        className={cn('shrink-0 text-amber-500', className)}
+        style={{ width: size, height: size }}
+      />
+    );
+  }
+
+  if (!svg) {
+    return (
+      <FileFallback
+        className={cn('shrink-0 text-muted-foreground/80', className)}
+        style={{ width: size, height: size }}
+      />
+    );
+  }
+
+  return (
+    <span
+      role="img"
+      aria-hidden
+      className={cn('inline-block shrink-0', className)}
+      style={{ width: size, height: size }}
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}
+
+export default FileIcon;

package/src/tools/FileIcon/index.ts

@@ -0,0 +1,9 @@
+'use client';
+
+export { FileIcon } from './FileIcon';
+export type { FileIconProps, FileIconSize } from './FileIcon';
+
+export { createFileIconSlot } from './treeAdapter';
+export type { CreateFileIconSlotOptions } from './treeAdapter';
+
+export { loadMaterialIcons, getMaterialIconsSync } from './loader';

package/src/tools/FileIcon/loader.ts

@@ -0,0 +1,47 @@
+'use client';
+
+/**
+ * Lazy loader for `material-file-icons`. The package is an optional dependency:
+ * if it's installed in the consumer's tree, we render its rich VSCode-style
+ * SVGs; if not, the loader resolves to `null` and `<FileIcon>` falls back to a
+ * Lucide icon. Either way, ui-tools never throws or warns about a missing
+ * package.
+ *
+ * Resolution is cached per-process so we don't re-import on every render.
+ */
+
+type GetIconFn = (name: string) => { svg: string } | undefined;
+
+let cached: GetIconFn | null | undefined;
+let inflight: Promise<GetIconFn | null> | null = null;
+
+export async function loadMaterialIcons(): Promise<GetIconFn | null> {
+  if (cached !== undefined) return cached;
+  if (inflight) return inflight;
+
+  inflight = (async () => {
+    try {
+      // Computed specifier so bundlers don't try to eagerly resolve it.
+      const specifier = 'material-file-icons';
+      const mod = (await import(/* @vite-ignore */ specifier)) as {
+        getIcon?: GetIconFn;
+        default?: { getIcon?: GetIconFn };
+      };
+      const fn = mod.getIcon ?? mod.default?.getIcon ?? null;
+      cached = fn;
+      return fn;
+    } catch {
+      cached = null;
+      return null;
+    } finally {
+      inflight = null;
+    }
+  })();
+
+  return inflight;
+}
+
+/** Synchronous accessor — returns null until `loadMaterialIcons` resolves. */
+export function getMaterialIconsSync(): GetIconFn | null {
+  return cached ?? null;
+}

package/src/tools/FileIcon/treeAdapter.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import type { TreeNode, TreeRowSlot } from '../Tree/types';
+import { FileIcon, type FileIconSize } from './FileIcon';
+
+export interface CreateFileIconSlotOptions<T> {
+  /**
+   * How to read the displayed name (with extension) for a node. Use the same
+   * accessor you pass to `<TreeRoot getItemName={...} />`.
+   */
+  getName: (node: TreeNode<T>) => string;
+  /** Pixel size for both file and folder icons. Default: 16. */
+  size?: FileIconSize;
+}
+
+/**
+ * Build a `renderIcon` slot for `<TreeRoot>` that uses `<FileIcon>` for both
+ * leaves and folders.
+ *
+ * @example
+ * ```tsx
+ * <TreeRoot
+ *   data={data}
+ *   getItemName={(n) => n.data.name}
+ *   renderIcon={createFileIconSlot({ getName: (n) => n.data.name })}
+ * />
+ * ```
+ */
+export function createFileIconSlot<T>({
+  getName,
+  size = 16,
+}: CreateFileIconSlotOptions<T>): TreeRowSlot<T> {
+  return ({ node, isFolder, isExpanded }) => (
+    <FileIcon
+      name={getName(node)}
+      isFolder={isFolder}
+      isExpanded={isExpanded}
+      size={size}
+    />
+  );
+}

package/src/tools/Tree/README.md

@@ -182,6 +182,7 @@ Toggle the bar with `appearance.showActiveIndicator`. Intensity scales with `app
 | Option | Default |
 | --- | --- |
 | `selectionMode` | `'single'` |
+| `activationMode` | `'single-click'` |
 | `enableSearch` | `false` |
 | `enableTypeAhead` | `true` |
 | `showIndentGuides` | `false` |
@@ -198,6 +199,7 @@ Toggle the bar with `appearance.showActiveIndicator`. Intensity scales with `app
 | Story | Demonstrates |
 | --- | --- |
 | Default | sensible cozy defaults |
+| WithActivationModes | single-click / double-click / preview semantics |
 | Densities | three density presets side-by-side |
 | WithIcons | file-type icons through `renderIcon` |
 | WithStatus | modified / error / disabled rows through `renderLabel` |
@@ -211,6 +213,60 @@ Toggle the bar with `appearance.showActiveIndicator`. Intensity scales with `app
 | LargeTree | ~500 nodes scalability check |
 | Playground | every knob exposed as a control |
 
+## Activation modes
+
+How a leaf becomes "activated" (opened) on pointer interaction is controlled
+by `activationMode`. Folders ignore this setting — they always toggle on
+single click and never call `onActivate`.
+
+| Mode | Single click | Double click |
+| --- | --- | --- |
+| `'single-click'` *(default)* | activate `{ preview: false }` | activate `{ preview: false }` |
+| `'double-click'` | select + focus only | activate `{ preview: false }` |
+| `'single-click-preview'` *(VSCode / Cursor)* | activate `{ preview: true }` | activate `{ preview: false }` |
+
+Keyboard `Enter` / `Space` always activates with `{ preview: false }` —
+keyboard input is treated as an explicit user action.
+
+```tsx
+<TreeRoot<FsNode>
+  data={data}
+  getItemName={(n) => n.data.name}
+  activationMode="single-click-preview"
+  onActivate={(node, { preview }) =>
+    preview ? openPreviewTab(node) : openPinnedTab(node)
+  }
+/>
+```
+
+The active mode is also exposed on each row as
+`data-activation-mode="<mode>"` for CSS-level targeting.
+
+## VSCode-style file icons
+
+Tree is generic over `T` — it has no opinion on whether nodes are files. For a
+ready-made VSCode-style icon set, install the optional companion subpath:
+
+```bash
+pnpm add material-file-icons
+```
+
+```tsx
+import { TreeRoot } from '@djangocfg/ui-tools/tree';
+import { createFileIconSlot } from '@djangocfg/ui-tools/file-icon';
+
+<TreeRoot
+  data={data}
+  getItemName={(n) => n.data.name}
+  renderIcon={createFileIconSlot({ getName: (n) => n.data.name })}
+/>
+```
+
+`material-file-icons` is declared in `optionalDependencies`. If it's not
+installed, `<FileIcon>` falls back to a Lucide `File` icon — no warnings, no
+runtime errors. Folders always render Lucide `Folder` / `FolderOpen` (amber
+tint), regardless of whether the optional package is present.
+
 ## Out of scope (today)
 
 - Inline rename UX

package/src/tools/Tree/Tree.story.tsx

@@ -111,6 +111,54 @@ export const Default = () => (
   </div>
 );
 
+// ---------------------------------------------------------------------------
+// 1.5) WithActivationModes — VSCode-style click semantics
+// ---------------------------------------------------------------------------
+
+export const WithActivationModes = () => {
+  const [log, setLog] = useState<string[]>([]);
+  const append = (s: string) =>
+    setLog((prev) => [s, ...prev].slice(0, 8));
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="grid grid-cols-3 gap-3">
+        {(['single-click', 'double-click', 'single-click-preview'] as const).map(
+          (mode) => (
+            <div key={mode} className="flex flex-col gap-2">
+              <span className="text-xs font-medium text-muted-foreground">
+                {mode}
+              </span>
+              <div className="h-72 w-64 rounded-md border border-border bg-card">
+                <TreeRoot<FsNode>
+                  data={fs}
+                  getItemName={getName}
+                  initialExpandedIds={['src']}
+                  activationMode={mode}
+                  onActivate={(node, { preview }) =>
+                    append(
+                      `[${mode}] ${node.data.name}${preview ? ' (preview)' : ''}`,
+                    )
+                  }
+                />
+              </div>
+            </div>
+          ),
+        )}
+      </div>
+      <div className="rounded-md border border-border bg-muted/30 p-3 font-mono text-xs">
+        {log.length === 0 ? (
+          <span className="text-muted-foreground">
+            click / double-click a file to log activations
+          </span>
+        ) : (
+          log.map((line, i) => <div key={i}>{line}</div>)
+        )}
+      </div>
+    </div>
+  );
+};
+
 // ---------------------------------------------------------------------------
 // 2) Densities — three presets side-by-side for comparison
 // ---------------------------------------------------------------------------

package/src/tools/Tree/TreeRoot.tsx

@@ -23,6 +23,7 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
     getItemName,
     loadChildren,
     selectionMode,
+    activationMode,
     initialExpandedIds,
     initialSelectedIds,
     indent,
@@ -51,6 +52,7 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
       getItemName={getItemName}
       loadChildren={loadChildren}
       selectionMode={selectionMode}
+      activationMode={activationMode}
       initialExpandedIds={initialExpandedIds}
       initialSelectedIds={initialSelectedIds}
       indent={indent}
@@ -97,22 +99,30 @@ function TreeRootShell<T>({
   const containerRef = useRef<HTMLDivElement>(null);
   const ctx = useTreeContext<T>();
 
-  // Keyboard navigation (↑↓ ←→ Home/End Enter Esc).
-  useTreeKeyboard<T>({
-    containerRef,
+  // Keyboard navigation (↑↓ ←→ Home/End Enter Esc) — scoped via callback ref.
+  const { ref: keyboardRef } = useTreeKeyboard<T>({
     rows: ctx.flatRows,
     focusedId: ctx.focused,
     onFocus: ctx.setFocus,
     onSelect: ctx.select,
     onActivate: (id) => {
+      // Keyboard Enter / Space is always an explicit action — pin (no preview).
       const row = ctx.flatRows.find((r) => r.node.id === id);
-      if (row) ctx.activate(row.node);
+      if (row) ctx.activate(row.node, { preview: false });
     },
     onExpand: ctx.expand,
     onCollapse: ctx.collapse,
     onClearSelection: ctx.clearSelection,
   });
 
+  const setContainerRef = useCallback(
+    (instance: HTMLDivElement | null) => {
+      containerRef.current = instance;
+      keyboardRef(instance);
+    },
+    [keyboardRef],
+  );
+
   // Type-ahead jump.
   const onTypeAheadMatch = useCallback(
     (id: string) => {
@@ -136,7 +146,7 @@ function TreeRootShell<T>({
 
   return (
     <div
-      ref={containerRef}
+      ref={setContainerRef}
       tabIndex={0}
       className={cn(
         'group/tree flex h-full w-full flex-col gap-2 outline-none',

package/src/tools/Tree/components/TreeRow.tsx

@@ -20,6 +20,7 @@ export function TreeRow<T>({ row, className }: TreeRowProps<T>) {
   const ctx = useTreeContext<T>();
   const {
     appearance,
+    activationMode,
     showIndentGuides,
     selected,
     focused,
@@ -51,31 +52,29 @@ export function TreeRow<T>({ row, className }: TreeRowProps<T>) {
     isMatchingSearch,
   };
 
-  const handleActivate = () => {
+  // Folders always toggle on single click regardless of `activationMode`.
+  // Leaves dispatch by mode:
+  //   single-click          → click activates {preview:false}
+  //   double-click          → click only selects; dblclick activates {preview:false}
+  //   single-click-preview  → click activates {preview:true}; dblclick activates {preview:false}
+  const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {
     if (node.disabled) return;
     setFocus(node.id);
     select(node.id);
-    if (isFolder) toggle(node.id);
-    else activate(node);
-  };
-
-  const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {
-    handleActivate();
+    if (isFolder) {
+      toggle(node.id);
+    } else if (activationMode === 'single-click') {
+      activate(node, { preview: false });
+    } else if (activationMode === 'single-click-preview') {
+      activate(node, { preview: true });
+    }
     e.currentTarget.scrollIntoView?.({ block: 'nearest' });
   };
 
   const handleDoubleClick = () => {
     if (node.disabled) return;
-    if (!isFolder) activate(node);
-  };
-
-  const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
-    // Match native button keyboard semantics on the row itself.
-    if (node.disabled) return;
-    if (e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      handleActivate();
-    }
+    if (isFolder) return;
+    activate(node, { preview: false });
   };
 
   const trigger = (
@@ -88,6 +87,7 @@ export function TreeRow<T>({ row, className }: TreeRowProps<T>) {
       aria-disabled={node.disabled || undefined}
       data-tree-row=""
       data-id={node.id}
+      data-activation-mode={activationMode}
       data-selected={isSelected ? 'true' : undefined}
       data-focused={isFocused && !isSelected ? 'true' : undefined}
       data-folder={isFolder || undefined}
@@ -100,7 +100,6 @@ export function TreeRow<T>({ row, className }: TreeRowProps<T>) {
       }}
       onClick={handleClick}
       onDoubleClick={handleDoubleClick}
-      onKeyDown={handleKeyDown}
       onFocus={() => setFocus(node.id)}
       className={cn(
         'group/row relative flex w-full select-none items-center pr-2 text-left',

package/src/tools/Tree/context/TreeContext.tsx

@@ -18,6 +18,8 @@ import {
   type TreeLabels,
   type TreeLoadChildren,
   type TreeNode,
+  type TreeActivateOptions,
+  type TreeActivationMode,
   type TreeRootProps,
   type TreeRowSlot,
   type TreeSelectionMode,
@@ -136,7 +138,7 @@ export interface TreeContextValue<T> {
   setQuery: (q: string) => void;
   refresh: (id: TreeItemId) => Promise<void>;
   refreshAll: () => Promise<void>;
-  activate: (node: TreeNode<T>) => void;
+  activate: (node: TreeNode<T>, opts?: TreeActivateOptions) => void;
 
   // Config / slots
   labels: TreeLabels;
@@ -145,6 +147,7 @@ export interface TreeContextValue<T> {
   /** Convenience alias for `appearance.indent`. */
   indent: number;
   selectionMode: TreeSelectionMode;
+  activationMode: TreeActivationMode;
   enableSearch: boolean;
   showIndentGuides: boolean;
   getItemName: (node: TreeNode<T>) => string;
@@ -176,6 +179,7 @@ export interface TreeProviderProps<T>
     | 'getItemName'
     | 'loadChildren'
     | 'selectionMode'
+    | 'activationMode'
     | 'initialExpandedIds'
     | 'initialSelectedIds'
     | 'indent'
@@ -225,6 +229,7 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
     getItemName,
     loadChildren,
     selectionMode = 'single',
+    activationMode = 'single-click',
     initialExpandedIds,
     initialSelectedIds,
     indent,
@@ -457,7 +462,8 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
   }, [loadChildren, state.expanded, nodeById, fetchChildren]);
 
   const activate = useCallback(
-    (node: TreeNode<T>) => onActivateRef.current?.(node),
+    (node: TreeNode<T>, opts: TreeActivateOptions = { preview: false }) =>
+      onActivateRef.current?.(node, opts),
     [],
   );
 
@@ -486,6 +492,7 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
       appearance: resolvedAppearance,
       indent: resolvedAppearance.indent,
       selectionMode,
+      activationMode,
       enableSearch,
       showIndentGuides,
       getItemName,
@@ -517,6 +524,7 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
       labels,
       resolvedAppearance,
       selectionMode,
+      activationMode,
       enableSearch,
       showIndentGuides,
       getItemName,