@djangocfg/ui-tools 2.1.317 → 2.1.318

package/dist/{types-Cclwv4Hl.d.cts → types-CevSbyfD.d.cts}

@@ -159,6 +159,12 @@ interface TreeRootProps<T> {
      * on `activationMode`). Folders never call this — they toggle instead.
      */
     onActivate?: (node: TreeNode<T>, opts: TreeActivateOptions) => void;
+    /**
+     * Optional predicate. Nodes returning `false` (and their descendants) are
+     * not rendered and not searchable. Use this to hide dot-files, system
+     * entries, or anything else the consumer wants to filter out.
+     */
+    filterNode?: (node: TreeNode<T>) => boolean;
     /** Show built-in search input. Default: false. */
     enableSearch?: boolean;
     /** Type printable letters to jump to a matching name. Default: true. */

package/dist/{types-Cclwv4Hl.d.ts → types-CevSbyfD.d.ts}

@@ -159,6 +159,12 @@ interface TreeRootProps<T> {
      * on `activationMode`). Folders never call this — they toggle instead.
      */
     onActivate?: (node: TreeNode<T>, opts: TreeActivateOptions) => void;
+    /**
+     * Optional predicate. Nodes returning `false` (and their descendants) are
+     * not rendered and not searchable. Use this to hide dot-files, system
+     * entries, or anything else the consumer wants to filter out.
+     */
+    filterNode?: (node: TreeNode<T>) => boolean;
     /** Show built-in search input. Default: false. */
     enableSearch?: boolean;
     /** Type printable letters to jump to a matching name. Default: true. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.317",
+  "version": "2.1.318",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -101,8 +101,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.317",
-    "@djangocfg/ui-core": "^2.1.317",
+    "@djangocfg/i18n": "^2.1.318",
+    "@djangocfg/ui-core": "^2.1.318",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -155,10 +155,10 @@
     "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.317",
+    "@djangocfg/i18n": "^2.1.318",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.317",
-    "@djangocfg/ui-core": "^2.1.317",
+    "@djangocfg/typescript-config": "^2.1.318",
+    "@djangocfg/ui-core": "^2.1.318",
     "@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

@@ -1,10 +1,11 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { File as FileFallback, Folder, FolderOpen } from 'lucide-react';
+import { File as FileFallback } from 'lucide-react';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { getMaterialIconsSync, loadMaterialIcons } from './loader';
+import { resolveFolderIcon, type FolderIconOverrides } from './specialFolders';
 
 export type FileIconSize = 12 | 14 | 16 | 18 | 20 | 24 | 28 | 32 | 40 | 48 | 64;
 
@@ -17,6 +18,11 @@ export interface FileIconProps {
   isExpanded?: boolean;
   /** Pixel size of the icon. */
   size?: FileIconSize;
+  /**
+   * Override or extend the built-in special-folder mapping. Keys are
+   * matched case-insensitively. Only used when `isFolder` is true.
+   */
+  folderOverrides?: FolderIconOverrides;
   className?: string;
 }
 
@@ -35,6 +41,7 @@ export function FileIcon({
   isFolder = false,
   isExpanded = false,
   size = 16,
+  folderOverrides,
   className,
 }: FileIconProps) {
   const [svg, setSvg] = useState<string | null>(() => {
@@ -59,7 +66,11 @@ export function FileIcon({
   }, [isFolder, name]);
 
   if (isFolder) {
-    const Icon = isExpanded ? FolderOpen : Folder;
+    const Icon = resolveFolderIcon({
+      name,
+      isExpanded,
+      overrides: folderOverrides,
+    });
     return (
       <Icon
         className={cn('shrink-0 text-amber-500', className)}

package/src/tools/FileIcon/index.ts

@@ -6,4 +6,10 @@ export type { FileIconProps, FileIconSize } from './FileIcon';
 export { createFileIconSlot } from './treeAdapter';
 export type { CreateFileIconSlotOptions } from './treeAdapter';
 
+export { resolveFolderIcon } from './specialFolders';
+export type {
+  ResolveFolderIconOptions,
+  FolderIconOverrides,
+} from './specialFolders';
+
 export { loadMaterialIcons, getMaterialIconsSync } from './loader';

package/src/tools/FileIcon/specialFolders.ts

@@ -0,0 +1,93 @@
+'use client';
+
+import {
+  BookOpen,
+  FlaskConical,
+  Folder,
+  FolderCode,
+  FolderGit2,
+  FolderInput,
+  FolderOpen,
+  FolderOutput,
+  Github,
+  Image as ImageIcon,
+  Package,
+  Settings,
+  Terminal,
+  type LucideIcon,
+} from 'lucide-react';
+
+/**
+ * Conventional folder names → Lucide icon. Lookup is case-insensitive and
+ * trimmed. Anything not in this map falls back to a generic folder icon.
+ *
+ * Designed to feel "right" across the common dev project layouts (Node,
+ * Python, Go, Rust, Django, Next, Vite). Not exhaustive on purpose —
+ * keeps the bundle light and the behaviour predictable.
+ */
+const SPECIAL_FOLDERS: Record<string, LucideIcon> = {
+  src: FolderCode,
+  source: FolderCode,
+  lib: FolderCode,
+  app: FolderCode,
+  packages: Package,
+  node_modules: Package,
+  vendor: Package,
+  public: FolderInput,
+  static: FolderInput,
+  assets: ImageIcon,
+  images: ImageIcon,
+  media: ImageIcon,
+  dist: FolderOutput,
+  build: FolderOutput,
+  out: FolderOutput,
+  '.next': FolderOutput,
+  '.nuxt': FolderOutput,
+  '.turbo': FolderOutput,
+  docs: BookOpen,
+  documentation: BookOpen,
+  tests: FlaskConical,
+  test: FlaskConical,
+  __tests__: FlaskConical,
+  __test__: FlaskConical,
+  scripts: Terminal,
+  bin: Terminal,
+  config: Settings,
+  configs: Settings,
+  '.config': Settings,
+  '.vscode': Settings,
+  '.idea': Settings,
+  '.git': FolderGit2,
+  '.github': Github,
+  '.gitlab': FolderGit2,
+};
+
+export interface ResolveFolderIconOptions {
+  /** Folder display name (no path). */
+  name: string;
+  /** Open / closed state — only used for the *generic* folder fallback. */
+  isExpanded?: boolean;
+  /**
+   * Optional override map. Wins over the built-in table. Keys are
+   * matched case-insensitively after `trim()`.
+   */
+  overrides?: Record<string, LucideIcon>;
+}
+
+/**
+ * Pick the right folder icon for `name`. Returns `Folder` / `FolderOpen`
+ * for unknown names so callers can render the generic open/closed pair.
+ */
+export function resolveFolderIcon({
+  name,
+  isExpanded = false,
+  overrides,
+}: ResolveFolderIconOptions): LucideIcon {
+  const key = name.trim().toLowerCase();
+  if (overrides?.[key]) return overrides[key];
+  const special = SPECIAL_FOLDERS[key];
+  if (special) return special;
+  return isExpanded ? FolderOpen : Folder;
+}
+
+export type FolderIconOverrides = Record<string, LucideIcon>;

package/src/tools/FileIcon/treeAdapter.tsx

@@ -2,6 +2,7 @@
 
 import type { TreeNode, TreeRowSlot } from '../Tree/types';
 import { FileIcon, type FileIconSize } from './FileIcon';
+import type { FolderIconOverrides } from './specialFolders';
 
 export interface CreateFileIconSlotOptions<T> {
   /**
@@ -11,6 +12,11 @@ export interface CreateFileIconSlotOptions<T> {
   getName: (node: TreeNode<T>) => string;
   /** Pixel size for both file and folder icons. Default: 16. */
   size?: FileIconSize;
+  /**
+   * Override or extend the built-in special-folder mapping (e.g. give
+   * `tests` a custom icon). Keys are matched case-insensitively.
+   */
+  folderOverrides?: FolderIconOverrides;
 }
 
 /**
@@ -29,6 +35,7 @@ export interface CreateFileIconSlotOptions<T> {
 export function createFileIconSlot<T>({
   getName,
   size = 16,
+  folderOverrides,
 }: CreateFileIconSlotOptions<T>): TreeRowSlot<T> {
   return ({ node, isFolder, isExpanded }) => (
     <FileIcon
@@ -36,6 +43,7 @@ export function createFileIconSlot<T>({
       isFolder={isFolder}
       isExpanded={isExpanded}
       size={size}
+      folderOverrides={folderOverrides}
     />
   );
 }

package/src/tools/Tree/README.md

@@ -200,6 +200,7 @@ Toggle the bar with `appearance.showActiveIndicator`. Intensity scales with `app
 | --- | --- |
 | Default | sensible cozy defaults |
 | WithActivationModes | single-click / double-click / preview semantics |
+| WithHiddenFilter | `filterNode` toggle hides dot-files |
 | Densities | three density presets side-by-side |
 | WithIcons | file-type icons through `renderIcon` |
 | WithStatus | modified / error / disabled rows through `renderLabel` |
@@ -213,6 +214,35 @@ Toggle the bar with `appearance.showActiveIndicator`. Intensity scales with `app
 | LargeTree | ~500 nodes scalability check |
 | Playground | every knob exposed as a control |
 
+## Filtering nodes
+
+`filterNode` is a single predicate that decides which nodes appear at all.
+Nodes returning `false` (and their descendants) are excluded from rendering,
+keyboard navigation, and search.
+
+```tsx
+const [showHidden, setShowHidden] = useState(false);
+
+<TreeRoot
+  data={data}
+  getItemName={(n) => n.data.name}
+  filterNode={(n) => showHidden || !n.data.name.startsWith('.')}
+/>
+```
+
+This is intentionally minimal — Tree is generic over `T` and has no opinion
+on what "hidden" means in your domain. If your backend already provides
+flags like `entry.isHidden` / `entry.isSystem`, use them directly:
+
+```tsx
+filterNode={(n) => showHidden || (!n.data.isHidden && !n.data.isSystem)}
+```
+
+> **Frontend note.** From the browser you cannot read OS-level hidden
+> attributes (Windows `FILE_ATTRIBUTE_HIDDEN`, macOS `kIsInvisible`).
+> Either filter by name (Unix dot-prefix is the de-facto convention), or
+> let your backend determine those flags and forward them in `node.data`.
+
 ## Activation modes
 
 How a leaf becomes "activated" (opened) on pointer interaction is controlled
@@ -264,8 +294,22 @@ import { createFileIconSlot } from '@djangocfg/ui-tools/file-icon';
 
 `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.
+runtime errors.
+
+Folders use a small built-in mapping (`src` → `FolderCode`,
+`node_modules` → `Package`, `.git` → `FolderGit2`, `dist`/`build`/`.next`
+→ `FolderOutput`, `tests`/`__tests__` → `FlaskConical`, …). Anything not
+in the table renders the generic `Folder` / `FolderOpen` pair. Override
+or extend the table per-call:
+
+```tsx
+import { FolderHeart } from 'lucide-react';
+
+renderIcon={createFileIconSlot({
+  getName: (n) => n.data.name,
+  folderOverrides: { favorites: FolderHeart },
+})}
+```
 
 ## Out of scope (today)
 

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

@@ -159,6 +159,42 @@ export const WithActivationModes = () => {
   );
 };
 
+// ---------------------------------------------------------------------------
+// 1.7) WithHiddenFilter — filterNode prop hides dot-prefixed entries
+// ---------------------------------------------------------------------------
+
+const fsWithDotfiles: TreeNode<FsNode>[] = [
+  ...fs,
+  { id: '.env', data: { name: '.env' } },
+  { id: '.gitignore', data: { name: '.gitignore' } },
+  {
+    id: '.git',
+    data: { name: '.git' },
+    isFolder: true,
+    children: [
+      { id: '.git/HEAD', data: { name: 'HEAD' } },
+      { id: '.git/config', data: { name: 'config' } },
+    ],
+  },
+];
+
+export const WithHiddenFilter = () => {
+  const [showHidden] = useBoolean('showHidden', {
+    defaultValue: false,
+    label: 'Show hidden',
+  });
+  return (
+    <div className="h-96 w-80 rounded-md border border-border bg-card">
+      <TreeRoot<FsNode>
+        data={fsWithDotfiles}
+        getItemName={getName}
+        initialExpandedIds={['src']}
+        filterNode={(n) => showHidden || !n.data.name.startsWith('.')}
+      />
+    </div>
+  );
+};
+
 // ---------------------------------------------------------------------------
 // 2) Densities — three presets side-by-side for comparison
 // ---------------------------------------------------------------------------

package/src/tools/Tree/TreeRoot.tsx

@@ -31,6 +31,7 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
     onSelectionChange,
     onExpansionChange,
     onActivate,
+    filterNode,
     enableSearch = false,
     enableTypeAhead = true,
     showIndentGuides = false,
@@ -60,6 +61,7 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
       onSelectionChange={onSelectionChange}
       onExpansionChange={onExpansionChange}
       onActivate={onActivate}
+      filterNode={filterNode}
       enableSearch={enableSearch}
       showIndentGuides={showIndentGuides}
       renderIcon={renderIcon}

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

@@ -4,6 +4,7 @@ import { Fragment, type ReactNode } from 'react';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { useTreeContext } from '../context/TreeContext';
+import { appearanceToStyle } from '../data/appearance';
 import type { FlatRow, TreeRowRenderProps, TreeRowSlot } from '../types';
 import { TreeRow } from './TreeRow';
 import { TreeEmpty } from './TreeEmpty';
@@ -17,7 +18,7 @@ export interface TreeContentProps<T> {
 }
 
 export function TreeContent<T>({ children, className, ariaLabel }: TreeContentProps<T>) {
-  const { flatRows, labels, selected, focused, matchingIds } = useTreeContext<T>();
+  const { flatRows, labels, selected, focused, matchingIds, appearance } = useTreeContext<T>();
 
   if (flatRows.length === 0) {
     return <TreeEmpty>{labels.empty}</TreeEmpty>;
@@ -28,6 +29,7 @@ export function TreeContent<T>({ children, className, ariaLabel }: TreeContentPr
       role="tree"
       aria-label={ariaLabel ?? labels.ariaLabel}
       className={cn('relative flex flex-col py-1', className)}
+      style={appearanceToStyle(appearance)}
     >
       {flatRows.map((row: FlatRow<T>) => {
         const slot: TreeRowRenderProps<T> = {

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

@@ -187,6 +187,7 @@ export interface TreeProviderProps<T>
     | 'onSelectionChange'
     | 'onExpansionChange'
     | 'onActivate'
+    | 'filterNode'
     | 'enableSearch'
     | 'showIndentGuides'
     | 'renderIcon'
@@ -237,6 +238,7 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
     onSelectionChange,
     onExpansionChange,
     onActivate,
+    filterNode,
     enableSearch = false,
     showIndentGuides = false,
     renderIcon,
@@ -350,8 +352,9 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
         roots: data,
         expandedIds: state.expanded,
         cache: cacheRef.current,
+        filterNode,
       }),
-    [data, state.expanded, state.cacheTick],
+    [data, state.expanded, state.cacheTick, filterNode],
   );
 
   // Search matches (case-insensitive substring on getItemName).

package/src/tools/Tree/data/flatten.ts

@@ -7,6 +7,8 @@ export interface FlattenInput<T> {
   roots: TreeNode<T>[];
   expandedIds: ReadonlySet<TreeItemId>;
   cache: ChildCache<T>;
+  /** Optional predicate. Nodes returning `false` (and their descendants) are excluded. */
+  filterNode?: (node: TreeNode<T>) => boolean;
 }
 
 const isNodeFolder = <T>(node: TreeNode<T>): boolean => {
@@ -21,11 +23,18 @@ const isNodeFolder = <T>(node: TreeNode<T>): boolean => {
  * `expandedIds`. The output is ordered exactly as it should render,
  * which keeps keyboard navigation (next/prev row) trivial.
  */
-export function flattenTree<T>({ roots, expandedIds, cache }: FlattenInput<T>): FlatRow<T>[] {
+export function flattenTree<T>({
+  roots,
+  expandedIds,
+  cache,
+  filterNode,
+}: FlattenInput<T>): FlatRow<T>[] {
   const out: FlatRow<T>[] = [];
 
   const walk = (nodes: TreeNode<T>[], level: number, parentId: TreeItemId | null) => {
     for (const node of nodes) {
+      if (filterNode && !filterNode(node)) continue;
+
       const isFolder = isNodeFolder(node);
       const isExpanded = expandedIds.has(node.id);
       const resolved = isFolder ? resolveChildren(cache, node) : { children: [], status: 'loaded' as const };

package/src/tools/Tree/types.ts

@@ -129,6 +129,13 @@ export interface TreeRootProps<T> {
    */
   onActivate?: (node: TreeNode<T>, opts: TreeActivateOptions) => void;
 
+  /**
+   * Optional predicate. Nodes returning `false` (and their descendants) are
+   * not rendered and not searchable. Use this to hide dot-files, system
+   * entries, or anything else the consumer wants to filter out.
+   */
+  filterNode?: (node: TreeNode<T>) => boolean;
+
   /** Show built-in search input. Default: false. */
   enableSearch?: boolean;
   /** Type printable letters to jump to a matching name. Default: true. */

package/dist/TreeRoot-R6XVHYQK.mjs

@@ -1,4 +0,0 @@
-export { TreeRoot, TreeRoot_default as default } from './chunk-NTJL2SXK.mjs';
-import './chunk-CGILA3WO.mjs';
-//# sourceMappingURL=TreeRoot-R6XVHYQK.mjs.map
-//# sourceMappingURL=TreeRoot-R6XVHYQK.mjs.map

package/dist/TreeRoot-RAMQSBMO.cjs

@@ -1,19 +0,0 @@
-'use strict';
-
-Object.defineProperty(exports, '__esModule', { value: true });
-
-var chunk44ZTWYAF_cjs = require('./chunk-44ZTWYAF.cjs');
-require('./chunk-WGEGR3DF.cjs');
-
-
-
-Object.defineProperty(exports, "TreeRoot", {
-  enumerable: true,
-  get: function () { return chunk44ZTWYAF_cjs.TreeRoot; }
-});
-Object.defineProperty(exports, "default", {
-  enumerable: true,
-  get: function () { return chunk44ZTWYAF_cjs.TreeRoot_default; }
-});
-//# sourceMappingURL=TreeRoot-RAMQSBMO.cjs.map
-//# sourceMappingURL=TreeRoot-RAMQSBMO.cjs.map