@djangocfg/ui-tools 2.1.413 → 2.1.416

package/dist/tree/index.d.ts

@@ -1,7 +1,308 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { T as TreeRootProps, a as TreeItemId, b as TreeNode, F as FlatRow, c as TreeActivateOptions, d as TreeLabels, R as ResolvedAppearance, e as TreeSelectionMode, f as TreeActivationMode, g as TreeRowSlot, h as TreeContextMenuSlot } from '../types-j2vhn4Kv.js';
-export { D as DEFAULT_TREE_APPEARANCE, n as DEFAULT_TREE_LABELS, l as TreeAccentIntensity, j as TreeAppearance, p as TreeContextMenuAction, s as TreeContextMenuActionsResolver, q as TreeContextMenuItem, k as TreeDensity, t as TreeLoadChildren, m as TreeRadius, o as TreeRowRenderProps, i as appearanceToStyle, r as resolveAppearance } from '../types-j2vhn4Kv.js';
 import * as react from 'react';
+import { CSSProperties } from 'react';
+import { T as TreeNode, a as TreeItemId, b as TreeRowSlot, c as TreeContextMenuSlot, d as TreeContextMenuActionsResolver, F as FlatRow, e as TreeRowRenderProps, f as TreeContextMenuItem } from '../slots-ClRpIzoh.js';
+export { g as TreeContextMenuAction, h as TreeContextMenuActionsContext } from '../slots-ClRpIzoh.js';
+
+type TreeSelectionMode = 'none' | 'single' | 'multiple';
+
+/**
+ * How a node becomes "activated" (i.e. opened) on pointer interaction.
+ *
+ *   - `'single-click'` (default): single click activates a leaf immediately;
+ *     double-click also activates. Folders always toggle on single click.
+ *   - `'double-click'`: single click only selects + focuses; double-click is
+ *     required to activate. Mirrors classic file-manager behaviour.
+ *   - `'single-click-preview'`: VSCode Explorer / Cursor behaviour. Single
+ *     click activates with `{ preview: true }` (consumer renders a preview
+ *     tab); double-click activates with `{ preview: false }` (pinned tab).
+ *
+ * Folders ignore this setting — they always toggle on single click and
+ * never call `onActivate`.
+ */
+type TreeActivationMode = 'single-click' | 'double-click' | 'single-click-preview';
+interface TreeActivateOptions {
+    /**
+     * `true` when the activation came from a single click in
+     * `'single-click-preview'` mode. `false` for double-click and for
+     * non-preview modes. Consumers typically map this to a
+     * preview-tab vs pinned-tab distinction.
+     */
+    preview: boolean;
+}
+
+/**
+ * Async loader: called the first time a folder is expanded with no inline
+ * `children`. Result is cached; concurrent expansions are de-duplicated.
+ */
+type TreeLoadChildren<T> = (node: TreeNode<T>) => Promise<TreeNode<T>[]>;
+
+interface TreeLabels {
+    loading: string;
+    empty: string;
+    error: string;
+    searchPlaceholder: string;
+    searchMatches: (count: number) => string;
+    ariaLabel: string;
+    /** Default context-menu item labels. */
+    actionOpen: string;
+    actionRename: string;
+    actionDuplicate: string;
+    actionCut: string;
+    actionCopy: string;
+    actionPaste: string;
+    actionDelete: string;
+    actionNewFile: string;
+    actionNewFolder: string;
+    /** Delete confirmation dialog. */
+    confirmDeleteTitle: (count: number) => string;
+    confirmDeleteMessage: (names: string[]) => string;
+    confirmDeleteOk: string;
+    confirmDeleteCancel: string;
+    /** New file prompt. */
+    newFileTitle: string;
+    newFileMessage: string;
+    newFilePlaceholder: string;
+    newFileDefault: string;
+    /** New folder prompt. */
+    newFolderTitle: string;
+    newFolderMessage: string;
+    newFolderPlaceholder: string;
+    newFolderDefault: string;
+    /** Rename prompt (used when inline rename is unavailable / disabled). */
+    renameTitle: string;
+    renameMessage: string;
+    /** Name validation. */
+    invalidNameEmpty: string;
+    /** Suffix used by the default `duplicate` flow when the consumer's adapter
+     *  needs a hint name. Receives the source name. */
+    duplicateSuffix: (name: string) => string;
+}
+declare const DEFAULT_TREE_LABELS: TreeLabels;
+
+/**
+ * Position of a drop / move relative to the target row. `inside` means
+ * "drop into this folder"; `before`/`after` are sibling reorder hints.
+ */
+type TreeMovePosition = 'before' | 'inside' | 'after';
+/**
+ * CRUD adapter. Every method is optional — Tree only surfaces built-in
+ * menu items / hotkeys whose adapter method is defined. So an
+ * inspection-only tree just passes `{}` (or no adapter) and gets no
+ * destructive menu actions.
+ *
+ * Dialogs (`alert` / `confirm` / `prompt`) are taken from `window.dialog`
+ * exposed by `<DialogProvider />` in `@djangocfg/ui-core`. The host app
+ * is expected to mount that provider once at the layout level — Tree
+ * never re-implements its own dialogs.
+ */
+interface TreeAdapter<T = unknown> {
+    /** Delete the given nodes. Tree calls `window.dialog.confirm` first. */
+    remove?: (nodes: TreeNode<T>[]) => Promise<void>;
+    /** Inline rename — node + new name (already non-empty, post-validate). */
+    rename?: (node: TreeNode<T>, nextName: string) => Promise<void>;
+    /** Create a file under `parent` (null → root). Tree prompts for name. */
+    createFile?: (parent: TreeNode<T> | null, name: string) => Promise<void>;
+    /** Create a folder under `parent` (null → root). Tree prompts for name. */
+    createFolder?: (parent: TreeNode<T> | null, name: string) => Promise<void>;
+    /** Duplicate the given nodes in-place. */
+    duplicate?: (nodes: TreeNode<T>[]) => Promise<void>;
+    /** Move nodes (drag-and-drop, cut+paste). */
+    move?: (nodes: TreeNode<T>[], target: TreeNode<T> | null, position: TreeMovePosition) => Promise<void>;
+    /** Copy nodes (copy+paste, drop with modifier). */
+    copy?: (nodes: TreeNode<T>[], target: TreeNode<T> | null, position: TreeMovePosition) => Promise<void>;
+    /**
+     * Optional name validator. Return a non-empty string to surface as an
+     * error via `window.dialog.alert`. Return `null` to accept.
+     */
+    validateName?: (name: string, ctx: {
+        node?: TreeNode<T>;
+        parent?: TreeNode<T> | null;
+    }) => string | null;
+}
+/**
+ * Built-in action ids. Used by `defaultMenuItems` and the internal
+ * built-in action registry. Each id maps 1:1 to an adapter method
+ * (plus a few selection helpers).
+ */
+type TreeBuiltinAction = 'open' | 'rename' | 'duplicate' | 'cut' | 'copy' | 'paste' | 'delete' | 'new-file' | 'new-folder';
+
+type TreeDensity = 'compact' | 'cozy' | 'comfortable';
+type TreeAccentIntensity = 'subtle' | 'default' | 'strong';
+type TreeRadius = 'none' | 'sm' | 'md';
+/**
+ * Cosmetic configuration. Every field is optional; missing values fall
+ * back to the `cozy` preset (a comfortable VSCode-Explorer-like density).
+ *
+ * Customize the look without re-implementing slots.
+ */
+interface TreeAppearance {
+    /** Built-in size preset. Default: `'cozy'`. */
+    density?: TreeDensity;
+    /** Override row height in px (wins over density). */
+    rowHeight?: number;
+    /** Override icon + chevron size in px (wins over density). */
+    iconSize?: number;
+    /** Lucide stroke width for icon + chevron. Default: 1.5. */
+    iconStrokeWidth?: number;
+    /** Override label font size in px (wins over density). */
+    fontSize?: number;
+    /** Pixels between chevron / icon / label. Default depends on density. */
+    gap?: number;
+    /** Pixels between nesting levels. Default: 16. */
+    indent?: number;
+    /** Hover / selected highlight intensity. Default: `'default'`. */
+    accent?: TreeAccentIntensity;
+    /** Row corner radius. Default: `'sm'`. */
+    radius?: TreeRadius;
+    /** Indent-guide line opacity (0..1). Default: 0.4. */
+    indentGuideOpacity?: number;
+    /**
+     * Show a 2px primary-tinted bar on the left of the selected row.
+     * Mimics the VSCode active-tab indicator. Default: `true`.
+     */
+    showActiveIndicator?: boolean;
+}
+interface ResolvedAppearance {
+    density: TreeDensity;
+    rowHeight: number;
+    iconSize: number;
+    iconStrokeWidth: number;
+    fontSize: number;
+    gap: number;
+    indent: number;
+    accent: TreeAccentIntensity;
+    radius: TreeRadius;
+    indentGuideOpacity: number;
+    showActiveIndicator: boolean;
+}
+declare const DEFAULT_TREE_APPEARANCE: ResolvedAppearance;
+/**
+ * Merge a partial appearance with the default + density preset.
+ *
+ * Explicit numeric overrides (e.g. `rowHeight`) win over the density preset.
+ */
+declare function resolveAppearance(input?: TreeAppearance, 
+/** Outer `indent` prop (kept on TreeRoot for back-compat). */
+outerIndent?: number): ResolvedAppearance;
+/**
+ * Build the `style` object that exposes the resolved appearance to any
+ * descendant via CSS variables. Set on `<TreeRoot>`'s outer div.
+ */
+declare function appearanceToStyle(a: ResolvedAppearance): CSSProperties;
+
+interface TreeRootProps<T> {
+    /** Root nodes. Top-level items are rendered directly (no synthetic root). */
+    data: TreeNode<T>[];
+    /** Returns the human-readable name for a node (used by search/type-ahead). */
+    getItemName: (node: TreeNode<T>) => string;
+    /** Async loader for folders without inline `children`. */
+    loadChildren?: TreeLoadChildren<T>;
+    /** Selection behaviour. Default: `'single'`. */
+    selectionMode?: TreeSelectionMode;
+    /** Pointer activation behaviour. Default: `'single-click'`. */
+    activationMode?: TreeActivationMode;
+    /** Initially expanded ids. */
+    initialExpandedIds?: TreeItemId[];
+    /** Initially selected ids. */
+    initialSelectedIds?: TreeItemId[];
+    /** Pixels of indent per nesting level. Default: 16. (Shortcut for `appearance.indent`.) */
+    indent?: number;
+    /** Cosmetic configuration: density, sizes, accent intensity, radius. */
+    appearance?: TreeAppearance;
+    /** Triggered when selection changes. */
+    onSelectionChange?: (selectedIds: TreeItemId[]) => void;
+    /** Triggered when expanded set changes. */
+    onExpansionChange?: (expandedIds: TreeItemId[]) => void;
+    /**
+     * Triggered when a leaf is activated (Enter / dblclick / click depending
+     * 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. */
+    enableTypeAhead?: boolean;
+    /** Render vertical indent guides under expanded folders. Default: false. */
+    showIndentGuides?: boolean;
+    /**
+     * Allow inline rename. When true, F2 starts an inline `<input>`; the
+     * value is committed through `adapter.rename`. Requires `adapter.rename`.
+     * Default: false.
+     */
+    enableInlineRename?: boolean;
+    /**
+     * Enable Finder/Explorer keyboard shortcuts (delete, rename, duplicate,
+     * new file/folder, cut/copy/paste). Bindings only fire when the tree
+     * container has focus. Individual shortcuts are still gated by the
+     * adapter — `⌘⌫` does nothing if `adapter.remove` is undefined.
+     * Default: false.
+     */
+    enableFinderHotkeys?: boolean;
+    /**
+     * Enable drag-and-drop reorder + move-into-folder. Requires
+     * `adapter.move`. Powered by `@dnd-kit/core` — pointer + keyboard
+     * sensors, accessible.
+     * Default: false.
+     */
+    enableDnD?: boolean;
+    /**
+     * Custom drop validation. Returns `true` to allow, `false` to forbid.
+     * The default validator rejects self-drops and cycles (dropping a
+     * folder into its own descendant). Use this to add domain rules
+     * (read-only branches, type matching, …).
+     */
+    canDrop?: (ctx: {
+        source: TreeNode<T>[];
+        target: TreeNode<T> | null;
+        position: TreeMovePosition;
+    }) => boolean;
+    /** Custom row renderer. Falls back to the default <TreeRow />. */
+    renderRow?: TreeRowSlot<T>;
+    /** Replace default folder/file icon. */
+    renderIcon?: TreeRowSlot<T>;
+    /** Replace default label rendering. */
+    renderLabel?: TreeRowSlot<T>;
+    /** Right-side actions slot (per row). */
+    renderActions?: TreeRowSlot<T>;
+    /** Wrap each row in a context menu (right-click). Receives the row meta + trigger element. */
+    renderContextMenu?: TreeContextMenuSlot<T>;
+    /**
+     * Declarative right-click menu — short-form. Pass `(row) => [items]` and the
+     * Tree builds a `<ContextMenu>` for you with sensible defaults. Ignored if
+     * `renderContextMenu` is also set. Return `null`/`undefined`/`[]` to skip
+     * the menu for that row.
+     */
+    contextMenuActions?: TreeContextMenuActionsResolver<T>;
+    /** Override built-in copy in your locale. */
+    labels?: Partial<TreeLabels>;
+    /** Persist expanded + (optional) selected ids in localStorage under this key. */
+    persistKey?: string;
+    /** Persist selection alongside expansion. Default: false. */
+    persistSelection?: boolean;
+    /**
+     * CRUD adapter. When set, Tree builds default context-menu items and
+     * Finder hotkeys for every method the adapter defines. Methods that
+     * are not provided produce no UI — no greyed-out items.
+     */
+    adapter?: TreeAdapter<T>;
+    /**
+     * Which built-in actions to expose in the auto-built context menu. If
+     * omitted, every action whose adapter method exists is shown.
+     *
+     * Pass `[]` to suppress the auto-built menu entirely while keeping the
+     * adapter for hotkeys / DnD.
+     */
+    defaultMenuItems?: TreeBuiltinAction[];
+    className?: string;
+    style?: CSSProperties;
+}
 
 /**
  * High-level entry point. Wraps Provider + (optional) search bar + content.
@@ -11,33 +312,88 @@ import * as react from 'react';
  */
 declare function TreeRoot<T>(props: TreeRootProps<T>): react_jsx_runtime.JSX.Element;
 
-type ChildEntryStatus = 'idle' | 'loading' | 'loaded' | 'error';
-interface ChildEntry<T> {
-    status: ChildEntryStatus;
-    children: TreeNode<T>[];
-    error?: string;
-}
-type ChildCache<T> = Map<TreeItemId, ChildEntry<T>>;
-declare const createChildCache: <T>() => ChildCache<T>;
 /**
- * Resolve a node's children for the current render.
+ * `<FinderTree>` — opinionated Finder/Explorer-style preset.
  *
- * - If the node carries inline `children`, those win (no async fetch).
- * - Otherwise we look in the cache.
+ * Equivalent to `<TreeRoot>` with multi-selection, double-click activation,
+ * inline rename, indent guides, and a cozy appearance turned on. Pass an
+ * `adapter` to get the built-in CRUD menu wired to `window.dialog.*`.
  *
- * Returns `null` when nothing is loaded yet (caller may show a skeleton).
+ * Override any preset default by simply passing the same prop:
+ *
+ * ```tsx
+ * <FinderTree<FsNode>
+ *   data={data}
+ *   getItemName={(n) => n.data.name}
+ *   adapter={fsAdapter}
+ *   // override one preset default — everything else stays Finder-y:
+ *   activationMode="single-click-preview"
+ * />
+ * ```
  */
-declare const resolveChildren: <T>(cache: ChildCache<T>, node: TreeNode<T>) => {
-    children: TreeNode<T>[] | null;
-    status: ChildEntryStatus;
-    error?: string;
-};
+declare function FinderTree<T>(props: TreeRootProps<T>): react_jsx_runtime.JSX.Element;
+
+type ClipboardKind = 'cut' | 'copy';
+interface ClipboardEntry {
+    kind: ClipboardKind;
+    ids: TreeItemId[];
+}
+type ClipboardState = ClipboardEntry | null;
+
+interface DropTargetState {
+    id: TreeItemId | null;
+    position: TreeMovePosition;
+}
+interface UseDndReturn<T> {
+    /** True when the host enabled DnD AND adapter.move is defined. */
+    active: boolean;
+    /** Ids currently being dragged (empty when not dragging). */
+    draggingIds: ReadonlySet<TreeItemId>;
+    /** Live drop target (`null` when nothing under the pointer). */
+    dropTarget: DropTargetState | null;
+    /** Called by row sensors on dragstart. */
+    beginDrag: (rowId: TreeItemId) => void;
+    /**
+     * Called on dragover. `null` clears the indicator. Tree already
+     * filters self/cycle drops via `defaultCanDrop` — the row component
+     * decides the position from pointer geometry first.
+     */
+    setDropTarget: (target: DropTargetState | null) => void;
+    /** Commit drop — calls `adapter.move` and resets transient state. */
+    commitDrop: () => Promise<void>;
+    /** Cancel without committing (Esc, drop outside). */
+    cancelDrag: () => void;
+    /**
+     * Validate a candidate drop in real time. Combines `defaultCanDrop`
+     * with the consumer's `canDrop`. Used by the row component to
+     * suppress the indicator on invalid hovers.
+     */
+    isAllowedDrop: (target: TreeNode<T> | null, position: TreeMovePosition) => boolean;
+}
+
+/**
+ * Click selection — derives next `{selected, anchor, focused}` from a
+ * pointer event's modifier keys. `rows` is the current flat view (used
+ * for shift-range computation).
+ */
+interface ClickModifiers {
+    shift: boolean;
+    meta: boolean;
+}
 
 interface TreeContextValue<T> {
     expanded: ReadonlySet<TreeItemId>;
     selected: ReadonlySet<TreeItemId>;
+    /** Anchor for shift-range. `null` when nothing has been clicked yet. */
+    anchor: TreeItemId | null;
     focused: TreeItemId | null;
     query: string;
+    /** Id of the row currently in inline-rename mode (or `null`). */
+    renamingId: TreeItemId | null;
+    /** Is inline rename allowed by the host? */
+    inlineRenameEnabled: boolean;
+    /** Tree-local clipboard (cut / copy) — P5. `null` when empty. */
+    clipboard: ClipboardState;
     flatRows: FlatRow<T>[];
     /** Search-matching node ids (subset of all flatRows). */
     matchingIds: ReadonlySet<TreeItemId>;
@@ -49,8 +405,44 @@ interface TreeContextValue<T> {
     select: (id: TreeItemId) => void;
     setSelectedIds: (ids: TreeItemId[]) => void;
     clearSelection: () => void;
+    /**
+     * Finder/Explorer-style click selection. Reads modifier keys from the
+     * passed event and decides between replace / toggle / range / union.
+     */
+    clickSelect: (id: TreeItemId, mods: ClickModifiers) => void;
+    /**
+     * Move-focus with optional range-extend (shift+arrows).
+     */
+    moveSelect: (id: TreeItemId, opts: {
+        extend: boolean;
+    }) => void;
+    /** Select every currently visible row (mod+a). */
+    selectAll: () => void;
     setFocus: (id: TreeItemId | null) => void;
     setQuery: (q: string) => void;
+    /** Put the given ids on Tree's clipboard as `cut`. */
+    cutToClipboard: (ids: TreeItemId[]) => void;
+    /** Put the given ids on Tree's clipboard as `copy`. */
+    copyToClipboard: (ids: TreeItemId[]) => void;
+    /**
+     * Apply clipboard onto `target` (a row, or `null` for the root). Cut →
+     * `adapter.move`; copy → `adapter.copy`. After a successful cut+paste
+     * the clipboard is cleared. No-op when clipboard is empty or the
+     * matching adapter method is undefined.
+     */
+    pasteFromClipboard: (target: TreeNode<T> | null, position?: TreeMovePosition) => Promise<void>;
+    /** Clear the clipboard without pasting. */
+    clearClipboard: () => void;
+    /** Begin inline rename on the given row. */
+    startRename: (id: TreeItemId) => void;
+    /** Cancel inline rename without committing. */
+    cancelRename: () => void;
+    /**
+     * Commit inline rename. Tree calls `adapter.rename` and then clears
+     * the renaming state. On validation failure surfaces an error via
+     * `window.dialog.alert` and keeps the input open.
+     */
+    commitRename: (id: TreeItemId, nextName: string) => Promise<boolean>;
     refresh: (id: TreeItemId) => Promise<void>;
     refreshAll: () => Promise<void>;
     activate: (node: TreeNode<T>, opts?: TreeActivateOptions) => void;
@@ -68,20 +460,155 @@ interface TreeContextValue<T> {
     renderLabel?: TreeRowSlot<T>;
     renderActions?: TreeRowSlot<T>;
     renderContextMenu?: TreeContextMenuSlot<T>;
+    /** CRUD adapter (P2). May be undefined — Tree still renders normally. */
+    adapter?: TreeAdapter<T>;
+    /**
+     * Final, merged declarative menu resolver. Combines built-in adapter
+     * actions (filtered by `defaultMenuItems`) with the consumer's
+     * `contextMenuActions` resolver, and injects the current
+     * `selectedNodes` before delegating.
+     */
+    resolvedContextMenuActions?: (row: TreeRowRenderProps<T>) => TreeContextMenuItem<T>[] | null | undefined;
+    /**
+     * Imperative lookup for any node currently known to Tree (root +
+     * cached async children).
+     */
+    getNodeById: (id: TreeItemId) => TreeNode<T> | undefined;
+    /**
+     * Drag-and-drop state and handlers (P6). `dnd.active` is `false`
+     * when the host didn't enable DnD or `adapter.move` is missing — in
+     * that case `TreeRow` skips all drag setup.
+     */
+    dnd: UseDndReturn<T>;
 }
+
+type ChildEntryStatus = 'idle' | 'loading' | 'loaded' | 'error';
+interface ChildEntry<T> {
+    status: ChildEntryStatus;
+    children: TreeNode<T>[];
+    error?: string;
+}
+type ChildCache<T> = Map<TreeItemId, ChildEntry<T>>;
+declare const createChildCache: <T>() => ChildCache<T>;
+/**
+ * Resolve a node's children for the current render.
+ *
+ * - If the node carries inline `children`, those win (no async fetch).
+ * - Otherwise we look in the cache.
+ *
+ * Returns `null` when nothing is loaded yet (caller may show a skeleton).
+ */
+declare const resolveChildren: <T>(cache: ChildCache<T>, node: TreeNode<T>) => {
+    children: TreeNode<T>[] | null;
+    status: ChildEntryStatus;
+    error?: string;
+};
+
 declare function useTreeContext<T>(): TreeContextValue<T>;
-interface TreeProviderProps<T> extends Pick<TreeRootProps<T>, 'data' | 'getItemName' | 'loadChildren' | 'selectionMode' | 'activationMode' | 'initialExpandedIds' | 'initialSelectedIds' | 'indent' | 'appearance' | 'onSelectionChange' | 'onExpansionChange' | 'onActivate' | 'filterNode' | 'enableSearch' | 'showIndentGuides' | 'renderIcon' | 'renderLabel' | 'renderActions' | 'renderContextMenu' | 'labels' | 'persistKey' | 'persistSelection'> {
+interface TreeProviderProps<T> extends Pick<TreeRootProps<T>, 'data' | 'getItemName' | 'loadChildren' | 'selectionMode' | 'activationMode' | 'initialExpandedIds' | 'initialSelectedIds' | 'indent' | 'appearance' | 'onSelectionChange' | 'onExpansionChange' | 'onActivate' | 'filterNode' | 'enableSearch' | 'showIndentGuides' | 'renderIcon' | 'renderLabel' | 'renderActions' | 'renderContextMenu' | 'contextMenuActions' | 'labels' | 'persistKey' | 'persistSelection' | 'adapter' | 'defaultMenuItems' | 'enableInlineRename' | 'enableDnD' | 'canDrop'> {
     children: react.ReactNode;
 }
 declare function TreeProvider<T>(props: TreeProviderProps<T>): react_jsx_runtime.JSX.Element;
 
+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;
+}
+/**
+ * Walk the tree top-to-bottom and produce a flat list of visible rows.
+ *
+ * Visibility rule: a child row appears only when every ancestor is in
+ * `expandedIds`. The output is ordered exactly as it should render,
+ * which keeps keyboard navigation (next/prev row) trivial.
+ */
+declare function flattenTree<T>({ roots, expandedIds, cache, filterNode, }: FlattenInput<T>): FlatRow<T>[];
+
+interface PersistedTreeState {
+    expandedItems: TreeItemId[];
+    selectedItems: TreeItemId[];
+}
+declare function loadTreeState(key: string): PersistedTreeState | null;
+declare function saveTreeState(key: string, state: PersistedTreeState): void;
+declare function clearTreeState(key: string): void;
+
+interface DemoNode {
+    name: string;
+}
+/**
+ * Build a deterministic synthetic tree for stories and tests.
+ *
+ * @example
+ *   const data = createDemoTree({ depth: 4, breadth: 3 });
+ *   <TreeRoot data={data} getItemName={(n) => n.data.name} />
+ */
+declare function createDemoTree({ depth, breadth, rootPrefix, }?: {
+    depth?: number;
+    breadth?: number;
+    rootPrefix?: string;
+}): TreeNode<DemoNode>[];
+
+interface SplitName {
+    base: string;
+    ext: string;
+}
+declare function splitFileName(name: string): SplitName;
+/**
+ * Returns the `[selectionStart, selectionEnd]` pair to use on focus of an
+ * `<input>` so only the base name is highlighted (Finder behaviour).
+ *
+ * Folders pass `isFolder=true` to skip extension detection and select
+ * the entire name — folders don't have file extensions semantically.
+ */
+declare function autoSelectRange(name: string, isFolder: boolean): [number, number];
+
+interface DropZoneInput {
+    /** Pointer Y in viewport coordinates. */
+    pointerY: number;
+    /** Row bounding box (`getBoundingClientRect()`). */
+    rowRect: {
+        top: number;
+        bottom: number;
+        height: number;
+    };
+    /** Folders accept `inside` drops; leaves only reorder via before/after. */
+    isFolder: boolean;
+}
+/**
+ * Translate pointer geometry into a drop position relative to the row.
+ *
+ * For folders the row is split into three zones (top third / middle /
+ * bottom third). For leaves it's split in half (before / after).
+ */
+declare function resolveDropZone(input: DropZoneInput): TreeMovePosition;
+interface CanDropInput<T> {
+    /** Nodes being dragged. */
+    source: TreeNode<T>[];
+    /** Row under the pointer (`null` = root drop zone). */
+    target: TreeNode<T> | null;
+    /** Resolved drop position. */
+    position: TreeMovePosition;
+    /** Tree's id→node lookup, used to walk descendants. */
+    getNodeById: (id: TreeItemId) => TreeNode<T> | undefined;
+}
+declare function defaultCanDrop<T>(input: CanDropInput<T>): boolean;
+declare const TREE_DND_MIME = "application/x-djangocfg-tree";
+
 declare function useTreeLabels(): TreeLabels;
 declare function useTreeRows<T>(): FlatRow<T>[];
 declare function useTreeSelection<T>(): {
     selectedIds: string[];
+    anchor: string;
     select: (id: TreeItemId) => void;
     setSelectedIds: (ids: TreeItemId[]) => void;
     clear: () => void;
+    clickSelect: (id: TreeItemId, mods: ClickModifiers) => void;
+    moveSelect: (id: TreeItemId, opts: {
+        extend: boolean;
+    }) => void;
+    selectAll: () => void;
     isSelected: (id: TreeItemId) => boolean;
 };
 declare function useTreeExpansion<T>(): {
@@ -104,6 +631,24 @@ declare function useTreeSearch<T>(): {
     matchingIds: ReadonlySet<string>;
     matchCount: number;
 };
+declare function useTreeDnd<T>(): UseDndReturn<T>;
+declare function useTreeClipboard<T>(): {
+    clipboard: ClipboardEntry;
+    isCut: (id: TreeItemId) => boolean;
+    cut: (ids: TreeItemId[]) => void;
+    copy: (ids: TreeItemId[]) => void;
+    paste: (target: TreeNode<T>, position?: TreeMovePosition) => Promise<void>;
+    clear: () => void;
+};
+declare function useTreeRename<T>(): {
+    /** True when the host allowed inline rename AND the adapter exposes `rename`. */
+    enabled: boolean;
+    /** Currently renaming id, or `null`. */
+    renamingId: string;
+    startRename: (id: TreeItemId) => void;
+    cancelRename: () => void;
+    commitRename: (id: TreeItemId, nextName: string) => Promise<boolean>;
+};
 declare function useTreeActions<T>(): {
     expand: (id: TreeItemId) => void;
     collapse: (id: TreeItemId) => void;
@@ -115,6 +660,53 @@ declare function useTreeActions<T>(): {
     activate: (node: TreeNode<T>, opts?: TreeActivateOptions) => void;
 };
 
+interface UseTreeKeyboardOptions<T> {
+    rows: FlatRow<T>[];
+    focusedId: TreeItemId | null;
+    enabled?: boolean;
+    /**
+     * `true` when `selectionMode === 'multiple'` — enables shift-extend on
+     * arrow keys, Home / End, and `Cmd/Ctrl+A` select-all. Without it the
+     * shift-modifier just moves focus.
+     */
+    multiSelect?: boolean;
+    /**
+     * Move focus to `id`. When `extend` is true and multi-select is enabled,
+     * the consumer should extend the selection range from anchor through id.
+     */
+    onFocus: (id: TreeItemId, opts: {
+        extend: boolean;
+    }) => void;
+    onSelect: (id: TreeItemId) => void;
+    onActivate: (id: TreeItemId) => void;
+    onExpand: (id: TreeItemId) => void;
+    onCollapse: (id: TreeItemId) => void;
+    onClearSelection: () => void;
+    /** Cmd/Ctrl+A — select all visible rows. Ignored if multiSelect is false. */
+    onSelectAll?: () => void;
+}
+interface UseTreeKeyboardReturn {
+    /** Attach to the tree container. Hotkeys only fire when focus is inside. */
+    ref: (instance: HTMLElement | null) => void;
+}
+
+/**
+ * Standard tree keyboard navigation, scoped to the container ref.
+ *
+ *   - ↑ / ↓          : prev / next visible row (Shift extends range)
+ *   - Home / End     : first / last visible row (Shift extends range)
+ *   - → / ←          : expand-or-jump-to-child / collapse-or-jump-to-parent
+ *   - Enter / Space  : activate (folder → toggle, leaf → onActivate)
+ *   - Esc            : clear selection
+ *   - Cmd/Ctrl + A   : select all (multi-select only)
+ *
+ * Pure decision-making lives in the sibling helpers (`arrow-nav.ts`,
+ * `expand-collapse.ts`, `activation.ts`) so it's unit-testable without
+ * a DOM. This file only wires up `useHotkey` bindings and dispatches
+ * the helper outcomes back to the consumer's callbacks.
+ */
+declare function useTreeKeyboard<T>({ rows, focusedId, enabled, multiSelect, onFocus, onSelect, onActivate, onExpand, onCollapse, onClearSelection, onSelectAll, }: UseTreeKeyboardOptions<T>): UseTreeKeyboardReturn;
+
 interface UseTreeTypeAheadOptions<T> {
     /** Visible flat rows in render order. */
     rows: FlatRow<T>[];
@@ -136,35 +728,66 @@ interface UseTreeTypeAheadOptions<T> {
  */
 declare function useTreeTypeAhead<T>({ rows, getItemName, containerRef, onMatch, enabled, }: UseTreeTypeAheadOptions<T>): void;
 
-interface UseTreeKeyboardOptions<T> {
-    rows: FlatRow<T>[];
-    focusedId: TreeItemId | null;
-    enabled?: boolean;
-    onFocus: (id: TreeItemId) => void;
-    onSelect: (id: TreeItemId) => void;
-    onActivate: (id: TreeItemId) => void;
-    onExpand: (id: TreeItemId) => void;
-    onCollapse: (id: TreeItemId) => void;
-    onClearSelection: () => void;
+interface BuiltinActionContext<T> {
+    adapter: TreeAdapter<T>;
+    labels: TreeLabels;
+    /** Currently selected nodes (full objects, resolved from ids). */
+    selectedNodes: TreeNode<T>[];
+    /** Row the user right-clicked / triggered the action on. May be null
+     *  for empty-area actions (paste / new file / new folder at root). */
+    targetNode: TreeNode<T> | null;
+    /** Returns the human-readable name for a node (uses `getItemName`). */
+    getName: (node: TreeNode<T>) => string;
+    /** Imperative: start inline rename on this id (no-op if disabled). */
+    startInlineRename?: (id: TreeItemId) => void;
+    /** Clipboard hooks (P5). Provided by Tree's context; pure forwarding. */
+    clipboard?: {
+        /** Current clipboard kind, if any (so we can hide "Paste" when empty). */
+        hasItems: boolean;
+        cut: (ids: TreeItemId[]) => void;
+        copy: (ids: TreeItemId[]) => void;
+        paste: () => void | Promise<void>;
+    };
 }
-interface UseTreeKeyboardReturn {
-    /** Attach to the tree container. Hotkeys only fire when focus is inside. */
+
+interface UseTreeFinderHotkeysOptions<T> {
+    /** Off by default — Tree opt-ins via `enableFinderHotkeys`. */
+    enabled: boolean;
+    /** Adapter — used both for action availability and dispatch. */
+    adapter?: TreeAdapter<T>;
+    /** Labels (passed through into adapter action context for dialogs). */
+    labels: TreeLabels;
+    /** Live selection (set of ids). */
+    selected: ReadonlySet<TreeItemId>;
+    /** Live focused id (used as "target" for new-file/new-folder actions). */
+    focused: TreeItemId | null;
+    /** Id → node lookup. */
+    getNodeById: (id: TreeItemId) => TreeNode<T> | undefined;
+    /** Display name resolver. */
+    getItemName: (node: TreeNode<T>) => string;
+    /** Open inline rename on the row (P3). Falls back to a prompt otherwise. */
+    startInlineRename?: (id: TreeItemId) => void;
+    /** Clipboard bindings (P5). When undefined, ⌘C/X/V are no-ops. */
+    clipboard?: BuiltinActionContext<T>['clipboard'];
+    /** Whether typing is currently in inline-rename input — pauses bindings. */
+    paused?: boolean;
+}
+interface UseTreeFinderHotkeysReturn {
+    /** Attach to the tree container ref so hotkeys only fire when it has focus. */
     ref: (instance: HTMLElement | null) => void;
 }
 /**
- * Standard tree keyboard navigation, scoped to the container ref.
- *
- *  - ↑ / ↓ : prev / next visible row
- *  - Home / End : first / last visible row
- *  - → : expand folder; if already expanded, jump to first child
- *  - ← : collapse folder; if already collapsed (or leaf), jump to parent
- *  - Enter / Space : activate (folder => toggle, leaf => onActivate)
- *  - Esc : clear selection
+ * Wire the platform-aware Finder/Explorer shortcuts to the built-in
+ * adapter actions. Bindings are scoped to the container ref via
+ * `useHotkey`, so they don't leak to the rest of the page.
  *
- * Built on `useHotkey` (react-hotkeys-hook) — focus gating is automatic; no
- * manual `addEventListener` or `data-scope` juggling.
+ * Each shortcut is bound by an explicit `useHotkey` call (no `.map(useHotkey)`
+ * loop, so the rules-of-hooks lint passes cleanly). The handler routes
+ * through `runBuiltinAction`, which silently no-ops when the adapter
+ * doesn't expose the matching method — so a Tree with `adapter = { remove }`
+ * only effectively reacts to ⌘⌫ / Delete.
  */
-declare function useTreeKeyboard<T>({ rows, focusedId, enabled, onFocus, onSelect, onActivate, onExpand, onCollapse, onClearSelection, }: UseTreeKeyboardOptions<T>): UseTreeKeyboardReturn;
+declare function useTreeFinderHotkeys<T>(opts: UseTreeFinderHotkeysOptions<T>): UseTreeFinderHotkeysReturn;
 
 interface TreeChevronProps {
     isExpanded: boolean;
@@ -273,44 +896,66 @@ interface TreeIndentGuidesProps {
  */
 declare function TreeIndentGuides({ level, indent }: TreeIndentGuidesProps): react_jsx_runtime.JSX.Element;
 
-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;
+interface TreeRenameInputProps {
+    initialValue: string;
+    isFolder: boolean;
+    /** Called with the new (trimmed) name when the user presses Enter / blurs. */
+    onCommit: (nextName: string) => void | Promise<unknown>;
+    /** Called when the user presses Escape. */
+    onCancel: () => void;
+    className?: string;
 }
 /**
- * Walk the tree top-to-bottom and produce a flat list of visible rows.
+ * Inline rename input rendered in place of `<TreeLabel>` while a row is
+ * being renamed. Mounts focused with the *base* portion of the name
+ * pre-selected (Finder behaviour — `foo.txt` selects `foo`).
  *
- * Visibility rule: a child row appears only when every ancestor is in
- * `expandedIds`. The output is ordered exactly as it should render,
- * which keeps keyboard navigation (next/prev row) trivial.
+ * Behaviour:
+ *   - Enter         → commit
+ *   - Escape        → cancel (no adapter call)
+ *   - blur          → commit (matches Finder; intentional even for empty
+ *                     names — the host validates and re-opens on error)
+ *   - all other keys are stopped from bubbling so Tree's container
+ *     hotkeys (↑↓ delete F2 etc.) don't fire while typing.
  */
-declare function flattenTree<T>({ roots, expandedIds, cache, filterNode, }: FlattenInput<T>): FlatRow<T>[];
+declare function TreeRenameInput({ initialValue, isFolder, onCommit, onCancel, className, }: TreeRenameInputProps): react_jsx_runtime.JSX.Element;
 
-interface PersistedTreeState {
-    expandedItems: TreeItemId[];
-    selectedItems: TreeItemId[];
+interface TreeDropIndicatorProps {
+    position: TreeMovePosition;
+    /** Indent in pixels — keeps the line aligned with the row's text. */
+    indent: number;
+    /** Render a "rejected" style (red wash) when the drop is forbidden. */
+    invalid?: boolean;
 }
-declare function loadTreeState(key: string): PersistedTreeState | null;
-declare function saveTreeState(key: string, state: PersistedTreeState): void;
-declare function clearTreeState(key: string): void;
+/**
+ * Visual hint for an in-progress drag-and-drop. Three modes:
+ *
+ *   - `before` / `after`  → a 2px horizontal line above / below the row
+ *   - `inside`            → a translucent primary wash filling the row
+ *
+ * Indents the line by the row's depth so it visually aligns with the
+ * target's content (rather than running edge-to-edge).
+ *
+ * Positioned absolutely — the parent `TreeRow` provides `position: relative`.
+ */
+declare function TreeDropIndicator({ position, indent, invalid, }: TreeDropIndicatorProps): react_jsx_runtime.JSX.Element;
 
-interface DemoNode {
-    name: string;
+interface TreeEmptyAreaProps {
+    className?: string;
 }
 /**
- * Build a deterministic synthetic tree for stories and tests.
+ * Fills the remaining vertical space below `<TreeContent>` so the user
+ * can right-click "into nothing" to get a Finder/Explorer-style empty
+ * area menu (paste / new file / new folder at root), and so DnD has a
+ * root drop target.
  *
- * @example
- *   const data = createDemoTree({ depth: 4, breadth: 3 });
- *   <TreeRoot data={data} getItemName={(n) => n.data.name} />
+ * Built-in actions are derived the same way as for rows — through
+ * `buildDefaultMenuItems`, with `targetNode = null` (root) and
+ * `selectedNodes = []` (nothing under the right-click). Items whose
+ * `available()` predicate fails are simply skipped, so a tree without
+ * `adapter.createFile/Folder` and without a clipboard payload shows
+ * no menu at all.
  */
-declare function createDemoTree({ depth, breadth, rootPrefix, }?: {
-    depth?: number;
-    breadth?: number;
-    rootPrefix?: string;
-}): TreeNode<DemoNode>[];
+declare function TreeEmptyArea({ className }: TreeEmptyAreaProps): react_jsx_runtime.JSX.Element;
 
-export { type ChildCache, type ChildEntry, type ChildEntryStatus, type DemoNode, FlatRow, type FlattenInput, type PersistedTreeState, ResolvedAppearance, TreeRoot as Tree, TreeActivateOptions, TreeActivationMode, TreeChevron, type TreeChevronProps, TreeContent, type TreeContentProps, TreeContextMenuSlot, type TreeContextValue, TreeEmpty, type TreeEmptyProps, TreeError, type TreeErrorProps, TreeIcon, type TreeIconProps, TreeIndentGuides, type TreeIndentGuidesProps, TreeItemId, TreeLabel, type TreeLabelProps, TreeLabels, TreeNode, TreeProvider, type TreeProviderProps, TreeRoot, TreeRootProps, TreeRow, type TreeRowProps, TreeRowSlot, TreeSearchInput, type TreeSearchInputProps, TreeSelectionMode, TreeSkeleton, type TreeSkeletonProps, type UseTreeKeyboardOptions, type UseTreeTypeAheadOptions, clearTreeState, createChildCache, createDemoTree, TreeRoot as default, flattenTree, loadTreeState, resolveChildren, saveTreeState, useTreeActions, useTreeContext, useTreeExpansion, useTreeFocus, useTreeKeyboard, useTreeLabels, useTreeRows, useTreeSearch, useTreeSelection, useTreeTypeAhead };
+export { type ChildCache, type ChildEntry, type ChildEntryStatus, DEFAULT_TREE_APPEARANCE, DEFAULT_TREE_LABELS, type DemoNode, FinderTree, FlatRow, type FlattenInput, type PersistedTreeState, type ResolvedAppearance, TREE_DND_MIME, TreeRoot as Tree, type TreeAccentIntensity, type TreeActivateOptions, type TreeActivationMode, type TreeAdapter, type TreeAppearance, type TreeBuiltinAction, TreeChevron, type TreeChevronProps, TreeContent, type TreeContentProps, TreeContextMenuActionsResolver, TreeContextMenuItem, TreeContextMenuSlot, type TreeContextValue, type TreeDensity, TreeDropIndicator, type TreeDropIndicatorProps, TreeEmpty, TreeEmptyArea, type TreeEmptyAreaProps, type TreeEmptyProps, TreeError, type TreeErrorProps, TreeIcon, type TreeIconProps, TreeIndentGuides, type TreeIndentGuidesProps, TreeItemId, TreeLabel, type TreeLabelProps, type TreeLabels, type TreeLoadChildren, type TreeMovePosition, TreeNode, TreeProvider, type TreeProviderProps, type TreeRadius, TreeRenameInput, type TreeRenameInputProps, TreeRoot, type TreeRootProps, TreeRow, type TreeRowProps, TreeRowRenderProps, TreeRowSlot, TreeSearchInput, type TreeSearchInputProps, type TreeSelectionMode, TreeSkeleton, type TreeSkeletonProps, type UseTreeFinderHotkeysOptions, type UseTreeKeyboardOptions, type UseTreeTypeAheadOptions, appearanceToStyle, autoSelectRange, clearTreeState, createChildCache, createDemoTree, TreeRoot as default, defaultCanDrop, flattenTree, loadTreeState, resolveAppearance, resolveChildren, resolveDropZone, saveTreeState, splitFileName, useTreeActions, useTreeClipboard, useTreeContext, useTreeDnd, useTreeExpansion, useTreeFinderHotkeys, useTreeFocus, useTreeKeyboard, useTreeLabels, useTreeRename, useTreeRows, useTreeSearch, useTreeSelection, useTreeTypeAhead };