@djangocfg/ui-tools 2.1.317 → 2.1.319

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. */