@djangocfg/widget-data 0.1.1

package/src/Tree/types/labels.ts

@@ -0,0 +1,97 @@
+'use client';
+
+export interface TreeLabels {
+  loading: string;
+  empty: string;
+  error: string;
+  searchPlaceholder: string;
+  searchMatches: (count: number) => string;
+  ariaLabel: string;
+
+  // ---- CRUD flow copy (used by built-in adapter actions + dialogs) ----
+
+  /** 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;
+}
+
+export const DEFAULT_TREE_LABELS: TreeLabels = {
+  loading: 'Loading…',
+  empty: 'Nothing to show',
+  error: 'Failed to load',
+  searchPlaceholder: 'Search…',
+  searchMatches: (n) => `${n} match${n === 1 ? '' : 'es'}`,
+  ariaLabel: 'Tree',
+
+  actionOpen: 'Open',
+  actionRename: 'Rename',
+  actionDuplicate: 'Duplicate',
+  actionCut: 'Cut',
+  actionCopy: 'Copy',
+  actionPaste: 'Paste',
+  actionDelete: 'Delete',
+  actionNewFile: 'New file',
+  actionNewFolder: 'New folder',
+
+  confirmDeleteTitle: (n) =>
+    n === 1 ? 'Delete item?' : `Delete ${n} items?`,
+  confirmDeleteMessage: (names) =>
+    names.length === 1
+      ? `"${names[0]}" will be removed. This action cannot be undone.`
+      : `${names.length} items will be removed. This action cannot be undone.`,
+  confirmDeleteOk: 'Delete',
+  confirmDeleteCancel: 'Cancel',
+
+  newFileTitle: 'New file',
+  newFileMessage: 'File name',
+  newFilePlaceholder: 'untitled.txt',
+  newFileDefault: 'untitled.txt',
+
+  newFolderTitle: 'New folder',
+  newFolderMessage: 'Folder name',
+  newFolderPlaceholder: 'untitled folder',
+  newFolderDefault: 'untitled folder',
+
+  renameTitle: 'Rename',
+  renameMessage: 'New name',
+
+  invalidNameEmpty: 'Name cannot be empty',
+
+  duplicateSuffix: (name) => `${name} copy`,
+};

package/src/Tree/types/loader.ts

@@ -0,0 +1,9 @@
+'use client';
+
+import type { TreeNode } from './node';
+
+/**
+ * Async loader: called the first time a folder is expanded with no inline
+ * `children`. Result is cached; concurrent expansions are de-duplicated.
+ */
+export type TreeLoadChildren<T> = (node: TreeNode<T>) => Promise<TreeNode<T>[]>;

package/src/Tree/types/node.ts

@@ -0,0 +1,38 @@
+'use client';
+
+export type TreeItemId = string;
+
+/** A single node in the consumer's tree data. Generic over your payload. */
+export interface TreeNode<T = unknown> {
+  id: TreeItemId;
+  data: T;
+  /** Inline children. Omit (and provide a `loadChildren`) for async loading. */
+  children?: TreeNode<T>[];
+  /**
+   * Set to `true` to mark a node as a folder even when its `children` array
+   * is empty (e.g. an unloaded async folder). Default: derived from
+   * `Array.isArray(children)`.
+   */
+  isFolder?: boolean;
+  /** Disable interaction. */
+  disabled?: boolean;
+}
+
+/**
+ * Internal flat-row representation used by the renderer + keyboard nav.
+ * Produced by `flattenTree`; consumed by `TreeRow`, the keyboard hook,
+ * and the type-ahead hook.
+ */
+export interface FlatRow<T> {
+  node: TreeNode<T>;
+  level: number;
+  parentId: TreeItemId | null;
+  isFolder: boolean;
+  isExpanded: boolean;
+  isLoading: boolean;
+  hasError: boolean;
+  /** 1-based position among visible siblings (for `aria-posinset`). */
+  posInSet: number;
+  /** Count of visible siblings sharing this row's parent (for `aria-setsize`). */
+  setSize: number;
+}

package/src/Tree/types/root-props.ts

@@ -0,0 +1,158 @@
+'use client';
+
+import type { CSSProperties } from 'react';
+
+import type { TreeAppearance } from '../data/appearance';
+import type { TreeActivateOptions, TreeActivationMode } from './activation';
+import type {
+  TreeAdapter,
+  TreeBuiltinAction,
+  TreeMovePosition,
+} from './adapter';
+import type { TreeLabels } from './labels';
+import type { TreeLoadChildren } from './loader';
+import type { TreeItemId, TreeNode } from './node';
+import type { TreeSelectionMode } from './selection';
+import type {
+  TreeContextMenuActionsResolver,
+  TreeContextMenuSlot,
+  TreeRowSlot,
+} from './slots';
+
+export 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[];
+
+  /**
+   * Imperative handle for outer code. The provided ref receives a
+   * stable handle to `useTreeActions` once Tree mounts. Lets host
+   * components trigger `refresh(id)` / `refreshAll()` from outside
+   * Tree (e.g. after a transport-level mutation completes).
+   */
+  actionsRef?: React.MutableRefObject<TreeActionsHandle | null>;
+
+  className?: string;
+  style?: CSSProperties;
+}
+
+/** Subset of `useTreeActions()` exposed via `<TreeRoot actionsRef={…}>`. */
+export interface TreeActionsHandle {
+  refresh: (id: string) => Promise<void>;
+  refreshAll: () => Promise<void>;
+  expandAll: () => void;
+  collapseAll: () => void;
+}

package/src/Tree/types/selection.ts

@@ -0,0 +1,3 @@
+'use client';
+
+export type TreeSelectionMode = 'none' | 'single' | 'multiple';

package/src/Tree/types/slots.ts

@@ -0,0 +1,64 @@
+'use client';
+
+import type { ComponentType, ReactNode } from 'react';
+
+import type { TreeNode } from './node';
+
+export interface TreeRowRenderProps<T> {
+  node: TreeNode<T>;
+  level: number;
+  isSelected: boolean;
+  isExpanded: boolean;
+  isFocused: boolean;
+  isFolder: boolean;
+  isLoading: boolean;
+  isMatchingSearch: boolean;
+}
+
+export type TreeRowSlot<T> = (props: TreeRowRenderProps<T>) => ReactNode;
+
+export type TreeContextMenuSlot<T> = (
+  props: TreeRowRenderProps<T>,
+  trigger: ReactNode,
+) => ReactNode;
+
+/**
+ * Declarative context-menu item. Pass `'separator'` (string) in place of an
+ * object to insert a `<ContextMenuSeparator />` between groups.
+ *
+ * For more advanced needs (submenus, checkbox items, custom JSX), drop down
+ * to `renderContextMenu` instead.
+ */
+export interface TreeContextMenuAction<T> {
+  /** Stable React key. */
+  id: string;
+  label: ReactNode;
+  /** Lucide-style icon component. Rendered as `<icon className="size-4" />`. */
+  icon?: ComponentType<{ className?: string }>;
+  /** Right-aligned keyboard hint (e.g. `'⌘C'`, `'↵'`). Cosmetic. */
+  shortcut?: ReactNode;
+  /** Disable the item — still rendered, not selectable. */
+  disabled?: boolean;
+  /** Style as destructive (red). */
+  destructive?: boolean;
+  /** Click / Enter handler. Receives the row meta. */
+  onSelect: (props: TreeRowRenderProps<T>) => void;
+}
+
+export type TreeContextMenuItem<T> = TreeContextMenuAction<T> | 'separator';
+
+/**
+ * Context passed to a `contextMenuActions` resolver. `row` is the row the
+ * user right-clicked. `selectedNodes` is the multi-selection at the
+ * moment the menu opens — when the right-clicked row was not in the
+ * selection, Tree first switches selection to that single row, so
+ * `selectedNodes` always contains the right-clicked node.
+ */
+export interface TreeContextMenuActionsContext<T> extends TreeRowRenderProps<T> {
+  /** Multi-selection at the moment the menu opens. Always non-empty. */
+  selectedNodes: TreeNode<T>[];
+}
+
+export type TreeContextMenuActionsResolver<T> = (
+  ctx: TreeContextMenuActionsContext<T>,
+) => TreeContextMenuItem<T>[] | null | undefined;

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Data surfaces: the components that put rows, nodes and cards on screen.
+ *
+ * A root barrel EXISTS here, unlike in the retired ui-tools, and the reason
+ * the ban was there does not apply: ui-tools mixed compiled `dist/` subpaths with raw
+ * `src/` ones, so a root barrel and a subpath resolved the same module twice
+ * and a `TreeProvider` context went missing. Every subpath here is source, so
+ * there is one resolution and one module instance.
+ *
+ * It still costs: importing the root pulls all nine trees. Prefer a subpath —
+ * `@djangocfg/widget-data/tree` — in an app that wants one.
+ */
+export * from './Tree';
+export * from './FileIcon';
+export * from './JsonTree';
+export * from './DataGrid';
+export * from './DataTable';
+export * from './Kanban';
+export * from './Listbox';
+export * from './Masonry';
+export * from './Timeline';

package/src/stories/_fixtures/categories.ts

@@ -0,0 +1,51 @@
+import type { TreeNode } from '../../Tree';
+
+export interface Category {
+  name: string;
+  count?: number;
+}
+
+export const CATEGORY_TREE: TreeNode<Category>[] = [
+  {
+    id: 'electronics',
+    data: { name: 'Electronics', count: 1240 },
+    children: [
+      {
+        id: 'computers',
+        data: { name: 'Computers', count: 410 },
+        children: [
+          { id: 'laptops', data: { name: 'Laptops', count: 220 } },
+          { id: 'desktops', data: { name: 'Desktops', count: 95 } },
+          { id: 'accessories', data: { name: 'Accessories', count: 95 } },
+        ],
+      },
+      {
+        id: 'phones',
+        data: { name: 'Phones', count: 530 },
+        children: [
+          { id: 'smartphones', data: { name: 'Smartphones', count: 480 } },
+          { id: 'phone-cases', data: { name: 'Cases', count: 50 } },
+        ],
+      },
+      { id: 'audio', data: { name: 'Audio', count: 300 } },
+    ],
+  },
+  {
+    id: 'home',
+    data: { name: 'Home & Garden', count: 870 },
+    children: [
+      { id: 'furniture', data: { name: 'Furniture', count: 320 } },
+      { id: 'kitchen', data: { name: 'Kitchen', count: 290 } },
+      { id: 'garden', data: { name: 'Garden', count: 260 } },
+    ],
+  },
+  {
+    id: 'apparel',
+    data: { name: 'Apparel', count: 1900 },
+    children: [
+      { id: 'mens', data: { name: "Men's", count: 800 } },
+      { id: 'womens', data: { name: "Women's", count: 900 } },
+      { id: 'kids', data: { name: 'Kids', count: 200 } },
+    ],
+  },
+];

package/src/stories/_fixtures/finder-store.ts

@@ -0,0 +1,196 @@
+import { useState } from 'react';
+
+import type {
+  TreeAdapter,
+  TreeItemId,
+  TreeMovePosition,
+  TreeNode,
+} from '../../Tree';
+
+export interface FsItem {
+  name: string;
+}
+
+export const FINDER_INITIAL: TreeNode<FsItem>[] = [
+  {
+    id: 'docs',
+    data: { name: 'docs' },
+    children: [
+      { id: 'docs/readme.md', data: { name: 'readme.md' } },
+      { id: 'docs/license.md', data: { name: 'license.md' } },
+    ],
+  },
+  {
+    id: 'src',
+    data: { name: 'src' },
+    children: [
+      { id: 'src/index.ts', data: { name: 'index.ts' } },
+      { id: 'src/utils.ts', data: { name: 'utils.ts' } },
+    ],
+  },
+  { id: 'package.json', data: { name: 'package.json' } },
+];
+
+interface Row {
+  id: TreeItemId;
+  data: FsItem;
+  parentId: TreeItemId | null;
+  isFolder: boolean;
+  order: number;
+}
+
+/**
+ * Tiny in-memory store for the Finder story.
+ *
+ * A flat `Row[]` is easier to mutate than a recursive `TreeNode<T>[]`;
+ * we project it back into a `TreeNode<FsItem>[]` on every render.
+ *
+ * Production hosts would normally drive this through their own data
+ * layer (REST, WebSocket, Wails → Go, …) — this implementation only
+ * exists so the story is fully interactive without a backend.
+ */
+export function useFinderStore(initial: TreeNode<FsItem>[]) {
+  const [rows, setRows] = useState<Row[]>(() => {
+    const out: Row[] = [];
+    let counter = 0;
+    const walk = (nodes: TreeNode<FsItem>[], parentId: TreeItemId | null) => {
+      for (const n of nodes) {
+        out.push({
+          id: n.id,
+          data: n.data,
+          parentId,
+          isFolder: Array.isArray(n.children) || !!n.isFolder,
+          order: counter++,
+        });
+        if (Array.isArray(n.children)) walk(n.children, n.id);
+      }
+    };
+    walk(initial, null);
+    return out;
+  });
+
+  const tree = projectTree(rows);
+
+  let nextId = rows.length;
+  const mintId = (): TreeItemId =>
+    `node-${++nextId}-${Math.random().toString(36).slice(2, 6)}`;
+
+  const collectDescendants = (id: TreeItemId, acc: Set<TreeItemId>) => {
+    acc.add(id);
+    for (const r of rows) if (r.parentId === id) collectDescendants(r.id, acc);
+  };
+
+  const resolveDropParent = (
+    target: TreeNode<FsItem> | null,
+    position: TreeMovePosition,
+  ): TreeItemId | null => {
+    if (!target) return null;
+    const targetRow = rows.find((r) => r.id === target.id);
+    if (!targetRow) return null;
+    return position === 'inside' && targetRow.isFolder
+      ? targetRow.id
+      : targetRow.parentId;
+  };
+
+  const adapter: TreeAdapter<FsItem> = {
+    remove: async (nodes) => {
+      const doomed = new Set<TreeItemId>();
+      for (const n of nodes) collectDescendants(n.id, doomed);
+      setRows((rs) => rs.filter((r) => !doomed.has(r.id)));
+    },
+    rename: async (node, name) => {
+      setRows((rs) =>
+        rs.map((r) => (r.id === node.id ? { ...r, data: { ...r.data, name } } : r)),
+      );
+    },
+    createFile: async (parent, name) => {
+      setRows((rs) => [
+        ...rs,
+        {
+          id: mintId(),
+          data: { name },
+          parentId: parent?.id ?? null,
+          isFolder: false,
+          order: rs.length,
+        },
+      ]);
+    },
+    createFolder: async (parent, name) => {
+      setRows((rs) => [
+        ...rs,
+        {
+          id: mintId(),
+          data: { name },
+          parentId: parent?.id ?? null,
+          isFolder: true,
+          order: rs.length,
+        },
+      ]);
+    },
+    duplicate: async (nodes) => {
+      setRows((rs) => {
+        const next = [...rs];
+        let order = rs.length;
+        for (const n of nodes) {
+          const src = rs.find((r) => r.id === n.id);
+          if (!src) continue;
+          next.push({
+            id: mintId(),
+            data: { ...src.data, name: `${src.data.name} copy` },
+            parentId: src.parentId,
+            isFolder: src.isFolder,
+            order: order++,
+          });
+        }
+        return next;
+      });
+    },
+    move: async (nodes, target, position) => {
+      const nodeIds = new Set(nodes.map((n) => n.id));
+      const nextParent = resolveDropParent(target, position);
+      setRows((rs) =>
+        rs.map((r) => (nodeIds.has(r.id) ? { ...r, parentId: nextParent } : r)),
+      );
+    },
+    copy: async (nodes, target, position) => {
+      const nextParent = resolveDropParent(target, position);
+      setRows((rs) => {
+        let order = rs.length;
+        const copies: Row[] = nodes.map((n) => {
+          const src = rs.find((r) => r.id === n.id)!;
+          return {
+            id: mintId(),
+            data: { ...src.data },
+            parentId: nextParent,
+            isFolder: src.isFolder,
+            order: order++,
+          };
+        });
+        return [...rs, ...copies];
+      });
+    },
+    validateName: (name) =>
+      name.trim().length === 0 ? 'Name cannot be empty' : null,
+  };
+
+  return { tree, adapter };
+}
+
+function projectTree(rows: Row[]): TreeNode<FsItem>[] {
+  const byParent = new Map<TreeItemId | null, Row[]>();
+  for (const r of [...rows].sort((a, b) => a.order - b.order)) {
+    const arr = byParent.get(r.parentId) ?? [];
+    arr.push(r);
+    byParent.set(r.parentId, arr);
+  }
+  const build = (parentId: TreeItemId | null): TreeNode<FsItem>[] => {
+    const list = byParent.get(parentId) ?? [];
+    return list.map<TreeNode<FsItem>>((r) => ({
+      id: r.id,
+      data: r.data,
+      isFolder: r.isFolder,
+      children: r.isFolder ? build(r.id) : undefined,
+    }));
+  };
+  return build(null);
+}