@djangocfg/widget-data 0.1.1

package/src/Tree/components/TreeEmptyArea.tsx

@@ -0,0 +1,160 @@
+'use client';
+
+import { useMemo } from 'react';
+import { useDroppable } from '@dnd-kit/core';
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuTrigger,
+} from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useTreeContext } from '../context/TreeContext';
+import {
+  buildDefaultMenuItems,
+  type BuiltinActionContext,
+} from '../context/menu';
+import { TREE_ROOT_DROP_ID } from '../data/dnd';
+import type { TreeContextMenuItem } from '../types';
+
+export interface TreeEmptyAreaProps {
+  className?: string;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function TreeEmptyArea({ className }: TreeEmptyAreaProps) {
+  const ctx = useTreeContext();
+  const {
+    adapter,
+    labels,
+    getItemName,
+    clipboard,
+    cutToClipboard,
+    copyToClipboard,
+    pasteFromClipboard,
+    startRename,
+    inlineRenameEnabled,
+    dnd,
+  } = ctx;
+
+  // Root drop target — receives drops that miss every row. The shared
+  // `TreeDndProvider.onDragMove` detects when `e.over.id === ROOT_DROP_ID`
+  // and pushes `{ id: null, position: 'inside' }` into `dnd.dropTarget`,
+  // so this component doesn't need an `onPointerMove` of its own.
+  const { setNodeRef: setDroppableRef, isOver } = useDroppable({
+    id: TREE_ROOT_DROP_ID,
+    disabled: !dnd.active,
+  });
+
+  // Resolve menu items every render — they depend on clipboard state
+  // (paste shows/hides) and on whether the adapter exposes
+  // createFile / createFolder.
+  const items = useMemo<TreeContextMenuItem<unknown>[] | null>(() => {
+    if (!adapter) return null;
+    const builtinCtx: BuiltinActionContext<unknown> = {
+      adapter,
+      labels,
+      selectedNodes: [],
+      targetNode: null,
+      getName: getItemName,
+      startInlineRename: inlineRenameEnabled ? startRename : undefined,
+      clipboard: {
+        hasItems: !!clipboard && clipboard.ids.length > 0,
+        cut: cutToClipboard,
+        copy: copyToClipboard,
+        paste: () => pasteFromClipboard(null, 'inside'),
+      },
+    };
+    return buildDefaultMenuItems(builtinCtx);
+  }, [
+    adapter,
+    labels,
+    getItemName,
+    inlineRenameEnabled,
+    startRename,
+    clipboard,
+    cutToClipboard,
+    copyToClipboard,
+    pasteFromClipboard,
+  ]);
+
+  const surface = (
+    <div
+      ref={dnd.active ? setDroppableRef : undefined}
+      data-tree-empty-area=""
+      data-drop-active={dnd.active && isOver ? 'true' : undefined}
+      className={cn(
+        // Soaks up the remaining vertical space inside the scroll
+        // container so right-click on whitespace lands here, not on
+        // the scroll viewport.
+        'min-h-[2.5rem] flex-1',
+        dnd.active && isOver && 'bg-primary/5 rounded-sm ring-1 ring-primary/30',
+        className,
+      )}
+    />
+  );
+
+  // No items and no DnD overlap → render plain spacer. Wrapping in a
+  // `<ContextMenu>` with zero items would still capture right-clicks
+  // and show an empty popover — that's worse than browser default.
+  if (!items || items.length === 0) {
+    return surface;
+  }
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>{surface}</ContextMenuTrigger>
+      <ContextMenuContent>
+        {items.map((item, idx) => {
+          if (item === 'separator') {
+            return <ContextMenuSeparator key={`sep-${idx}`} />;
+          }
+          const Icon = item.icon;
+          return (
+            <ContextMenuItem
+              key={item.id}
+              disabled={item.disabled}
+              variant={item.destructive ? 'destructive' : undefined}
+              // Pass a synthetic "no-target" row props — the built-in
+              // action handlers we surface here (new-file / new-folder
+              // / paste) don't read row-specific fields anyway.
+              onSelect={() =>
+                item.onSelect({
+                  node: undefined as never,
+                  level: 0,
+                  isSelected: false,
+                  isExpanded: false,
+                  isFocused: false,
+                  isFolder: false,
+                  isLoading: false,
+                  isMatchingSearch: false,
+                })
+              }
+            >
+              {Icon ? <Icon /> : null}
+              {item.label}
+              {item.shortcut ? (
+                <ContextMenuShortcut>{item.shortcut}</ContextMenuShortcut>
+              ) : null}
+            </ContextMenuItem>
+          );
+        })}
+      </ContextMenuContent>
+    </ContextMenu>
+  );
+}

package/src/Tree/components/TreeError.tsx

@@ -0,0 +1,24 @@
+'use client';
+
+import { AlertCircle } from 'lucide-react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface TreeErrorProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export function TreeError({ children, className }: TreeErrorProps) {
+  return (
+    <div
+      className={cn(
+        'flex items-start gap-2 rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive',
+        className,
+      )}
+      role="alert"
+    >
+      <AlertCircle aria-hidden className="mt-0.5 size-4 shrink-0" />
+      <span>{children}</span>
+    </div>
+  );
+}

package/src/Tree/components/TreeIcon.tsx

@@ -0,0 +1,39 @@
+'use client';
+
+import { File, Folder, FolderOpen } from 'lucide-react';
+import { memo } from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useTreeContext } from '../context/TreeContext';
+
+export interface TreeIconProps {
+  isFolder: boolean;
+  isExpanded: boolean;
+  className?: string;
+}
+
+/**
+ * TreeIcon — file/folder icon for a tree row.
+ *
+ * Memoised: re-renders only when `isFolder`, `isExpanded` or `className`
+ * change. Reads appearance from context — context updates will still
+ * trigger re-render as expected.
+ */
+function TreeIconRaw({ isFolder, isExpanded, className }: TreeIconProps) {
+  const { appearance } = useTreeContext();
+  const Icon = isFolder ? (isExpanded ? FolderOpen : Folder) : File;
+  return (
+    <Icon
+      aria-hidden
+      strokeWidth={appearance.iconStrokeWidth}
+      style={{ width: 'var(--tree-icon-size)', height: 'var(--tree-icon-size)' }}
+      className={cn(
+        'shrink-0',
+        isFolder ? 'text-foreground/70' : 'text-muted-foreground/80',
+        className,
+      )}
+    />
+  );
+}
+
+export const TreeIcon = memo(TreeIconRaw);

package/src/Tree/components/TreeIndentGuides.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import { useTreeContext } from '../context/TreeContext';
+
+export interface TreeIndentGuidesProps {
+  level: number;
+  indent: number;
+}
+
+/**
+ * Vertical guide lines under nested rows. Renders one absolute-positioned
+ * 1px column per ancestor level. Decorative — `aria-hidden` and
+ * pointer-events disabled. Opacity comes from the tree appearance.
+ */
+export function TreeIndentGuides({ level, indent }: TreeIndentGuidesProps) {
+  const { appearance } = useTreeContext();
+  if (level <= 0) return null;
+  return (
+    <span
+      aria-hidden
+      className="pointer-events-none absolute inset-y-0 left-0"
+      style={{ width: 8 + level * indent, opacity: appearance.indentGuideOpacity }}
+    >
+      {Array.from({ length: level }).map((_, i) => (
+        <span
+          key={i}
+          className="absolute inset-y-0 w-px bg-border"
+          style={{ left: 8 + i * indent + indent / 2 - 0.5 }}
+        />
+      ))}
+    </span>
+  );
+}

package/src/Tree/components/TreeLabel.tsx

@@ -0,0 +1,39 @@
+'use client';
+
+import { memo } from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface TreeLabelProps {
+  children: React.ReactNode;
+  isMatchingSearch?: boolean;
+  className?: string;
+}
+
+/**
+ * TreeLabel — truncated label for a tree row.
+ *
+ * Memoised: re-renders only when `children`, `isMatchingSearch` or
+ * `className` change. `children` is compared by reference.
+ */
+function TreeLabelRaw({ children, isMatchingSearch, className }: TreeLabelProps) {
+  return (
+    <span
+      // Colour is set inline via the semantic token rather than the
+      // `text-foreground` Tailwind utility: that class isn't always
+      // emitted into a consuming app's stylesheet (the bundler only
+      // generates utilities it sees referenced in scanned source), so
+      // relying on it left the label rendering as UA-default black on
+      // a dark surface. `var(--foreground)` always resolves.
+      style={{ fontSize: 'var(--tree-font-size)', color: 'var(--foreground)' }}
+      className={cn(
+        'truncate leading-tight tracking-[-0.005em]',
+        isMatchingSearch && 'font-medium',
+        className,
+      )}
+    >
+      {children}
+    </span>
+  );
+}
+
+export const TreeLabel = memo(TreeLabelRaw);

package/src/Tree/components/TreeRenameInput.tsx

@@ -0,0 +1,114 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { autoSelectRange } from '../data/renameUtils';
+
+export 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;
+}
+
+/**
+ * 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`).
+ *
+ * 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.
+ */
+export function TreeRenameInput({
+  initialValue,
+  isFolder,
+  onCommit,
+  onCancel,
+  className,
+}: TreeRenameInputProps) {
+  const [value, setValue] = useState(initialValue);
+  const inputRef = useRef<HTMLInputElement>(null);
+  // Track whether we already committed/cancelled so the blur handler
+  // doesn't fire a second time after Enter/Escape.
+  const settledRef = useRef(false);
+
+  useEffect(() => {
+    const el = inputRef.current;
+    if (!el) return;
+    el.focus();
+    const [start, end] = autoSelectRange(initialValue, isFolder);
+    // setSelectionRange on a freshly focused input — schedule on next
+    // tick to dodge browser quirks where focus() resets the selection.
+    requestAnimationFrame(() => {
+      try {
+        el.setSelectionRange(start, end);
+      } catch {
+        /* Some input types reject setSelectionRange — safe to ignore. */
+      }
+    });
+    // Run only once on mount.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const commit = () => {
+    if (settledRef.current) return;
+    settledRef.current = true;
+    void onCommit(value);
+  };
+
+  const cancel = () => {
+    if (settledRef.current) return;
+    settledRef.current = true;
+    onCancel();
+  };
+
+  return (
+    <input
+      ref={inputRef}
+      type="text"
+      value={value}
+      // Tree's container hotkeys (delete / arrows / F2 …) must not fire
+      // while the user is typing the new name.
+      onKeyDown={(e) => {
+        e.stopPropagation();
+        if (e.key === 'Enter') {
+          e.preventDefault();
+          commit();
+        } else if (e.key === 'Escape') {
+          e.preventDefault();
+          cancel();
+        }
+      }}
+      onChange={(e) => setValue(e.target.value)}
+      onBlur={commit}
+      // Prevent click/dblclick on the row from re-firing while the input
+      // is mounted (otherwise a focused click commits + re-selects).
+      onClick={(e) => e.stopPropagation()}
+      onDoubleClick={(e) => e.stopPropagation()}
+      onMouseDown={(e) => e.stopPropagation()}
+      // Right-click inside the input should be the native input menu,
+      // not the row's context menu.
+      onContextMenu={(e) => e.stopPropagation()}
+      className={cn(
+        'min-w-0 flex-1 rounded-sm border border-primary/50 bg-background',
+        'px-1 py-0 text-foreground outline-none',
+        'focus:ring-1 focus:ring-primary/40',
+        className,
+      )}
+      style={{
+        // Match the row's font metrics so the input doesn't visibly jolt.
+        fontSize: 'var(--tree-font-size)',
+        height: 'calc(var(--tree-row-height) - 4px)',
+      }}
+    />
+  );
+}