@djangocfg/ui-tools 2.1.314 → 2.1.316

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

@@ -0,0 +1,175 @@
+'use client';
+
+import type { CSSProperties } from 'react';
+
+export type TreeDensity = 'compact' | 'cozy' | 'comfortable';
+export type TreeAccentIntensity = 'subtle' | 'default' | 'strong';
+export 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.
+ */
+export 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;
+}
+
+export interface ResolvedAppearance {
+  density: TreeDensity;
+  rowHeight: number;
+  iconSize: number;
+  iconStrokeWidth: number;
+  fontSize: number;
+  gap: number;
+  indent: number;
+  accent: TreeAccentIntensity;
+  radius: TreeRadius;
+  indentGuideOpacity: number;
+  showActiveIndicator: boolean;
+}
+
+const DENSITY_PRESETS: Record<
+  TreeDensity,
+  Pick<ResolvedAppearance, 'rowHeight' | 'iconSize' | 'fontSize' | 'gap'>
+> = {
+  compact: { rowHeight: 24, iconSize: 14, fontSize: 13, gap: 6 },
+  cozy: { rowHeight: 28, iconSize: 16, fontSize: 13, gap: 8 },
+  comfortable: { rowHeight: 32, iconSize: 16, fontSize: 14, gap: 8 },
+};
+
+export const DEFAULT_TREE_APPEARANCE: ResolvedAppearance = {
+  density: 'cozy',
+  ...DENSITY_PRESETS.cozy,
+  iconStrokeWidth: 1.5,
+  indent: 16,
+  accent: 'default',
+  radius: 'sm',
+  indentGuideOpacity: 0.4,
+  showActiveIndicator: true,
+};
+
+/**
+ * Merge a partial appearance with the default + density preset.
+ *
+ * Explicit numeric overrides (e.g. `rowHeight`) win over the density preset.
+ */
+export function resolveAppearance(
+  input?: TreeAppearance,
+  /** Outer `indent` prop (kept on TreeRoot for back-compat). */
+  outerIndent?: number,
+): ResolvedAppearance {
+  if (!input && outerIndent === undefined) return DEFAULT_TREE_APPEARANCE;
+
+  const density: TreeDensity = input?.density ?? 'cozy';
+  const preset = DENSITY_PRESETS[density];
+
+  return {
+    density,
+    rowHeight: input?.rowHeight ?? preset.rowHeight,
+    iconSize: input?.iconSize ?? preset.iconSize,
+    iconStrokeWidth: input?.iconStrokeWidth ?? DEFAULT_TREE_APPEARANCE.iconStrokeWidth,
+    fontSize: input?.fontSize ?? preset.fontSize,
+    gap: input?.gap ?? preset.gap,
+    indent: input?.indent ?? outerIndent ?? DEFAULT_TREE_APPEARANCE.indent,
+    accent: input?.accent ?? DEFAULT_TREE_APPEARANCE.accent,
+    radius: input?.radius ?? DEFAULT_TREE_APPEARANCE.radius,
+    indentGuideOpacity:
+      input?.indentGuideOpacity ?? DEFAULT_TREE_APPEARANCE.indentGuideOpacity,
+    showActiveIndicator:
+      input?.showActiveIndicator ?? DEFAULT_TREE_APPEARANCE.showActiveIndicator,
+  };
+}
+
+/**
+ * Build the `style` object that exposes the resolved appearance to any
+ * descendant via CSS variables. Set on `<TreeRoot>`'s outer div.
+ */
+export function appearanceToStyle(a: ResolvedAppearance): CSSProperties {
+  return {
+    ['--tree-row-height' as string]: `${a.rowHeight}px`,
+    ['--tree-icon-size' as string]: `${a.iconSize}px`,
+    ['--tree-icon-stroke' as string]: a.iconStrokeWidth,
+    ['--tree-font-size' as string]: `${a.fontSize}px`,
+    ['--tree-gap' as string]: `${a.gap}px`,
+    ['--tree-indent' as string]: `${a.indent}px`,
+    ['--tree-guide-opacity' as string]: a.indentGuideOpacity,
+  };
+}
+
+const RADIUS_CLASS: Record<TreeRadius, string> = {
+  none: 'rounded-none',
+  sm: 'rounded-sm',
+  md: 'rounded-md',
+};
+export function radiusClass(a: ResolvedAppearance) {
+  return RADIUS_CLASS[a.radius];
+}
+
+/**
+ * VSCode-style row state classes.
+ *
+ *  - hover: subtle neutral wash
+ *  - focused (keyboard nav, not yet selected): slightly stronger neutral
+ *  - selected (tree NOT focused): muted neutral block
+ *  - selected + tree focused-within: primary-tinted block + colored text
+ *
+ * Intensity scales with `appearance.accent`.
+ */
+const HOVER: Record<TreeAccentIntensity, string> = {
+  subtle: 'hover:bg-foreground/[.03]',
+  default: 'hover:bg-foreground/[.06]',
+  strong: 'hover:bg-foreground/[.09]',
+};
+const FOCUSED_NOT_SELECTED: Record<TreeAccentIntensity, string> = {
+  subtle: 'data-[focused=true]:bg-foreground/[.05]',
+  default: 'data-[focused=true]:bg-foreground/[.08]',
+  strong: 'data-[focused=true]:bg-foreground/[.12]',
+};
+const SELECTED_INACTIVE: Record<TreeAccentIntensity, string> = {
+  subtle: 'data-[selected=true]:bg-foreground/[.06]',
+  default: 'data-[selected=true]:bg-foreground/[.10]',
+  strong: 'data-[selected=true]:bg-foreground/[.14]',
+};
+const SELECTED_ACTIVE: Record<TreeAccentIntensity, string> = {
+  subtle:
+    'data-[selected=true]:group-focus-within/tree:bg-primary/10 data-[selected=true]:group-focus-within/tree:text-primary',
+  default:
+    'data-[selected=true]:group-focus-within/tree:bg-primary/15 data-[selected=true]:group-focus-within/tree:text-primary',
+  strong:
+    'data-[selected=true]:group-focus-within/tree:bg-primary/25 data-[selected=true]:group-focus-within/tree:text-primary',
+};
+
+export function rowStateClasses(a: ResolvedAppearance) {
+  return [
+    HOVER[a.accent],
+    FOCUSED_NOT_SELECTED[a.accent],
+    SELECTED_INACTIVE[a.accent],
+    SELECTED_ACTIVE[a.accent],
+  ].join(' ');
+}

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

@@ -0,0 +1,43 @@
+'use client';
+
+import type { TreeItemId, TreeNode } from '../types';
+
+export type ChildEntryStatus = 'idle' | 'loading' | 'loaded' | 'error';
+
+export interface ChildEntry<T> {
+  status: ChildEntryStatus;
+  children: TreeNode<T>[];
+  error?: string;
+}
+
+export type ChildCache<T> = Map<TreeItemId, ChildEntry<T>>;
+
+export const createChildCache = <T>(): ChildCache<T> => new Map();
+
+export const getEntry = <T>(
+  cache: ChildCache<T>,
+  id: TreeItemId,
+): ChildEntry<T> | undefined => cache.get(id);
+
+/**
+ * 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).
+ */
+export const resolveChildren = <T>(
+  cache: ChildCache<T>,
+  node: TreeNode<T>,
+): { children: TreeNode<T>[] | null; status: ChildEntryStatus; error?: string } => {
+  if (Array.isArray(node.children)) {
+    return { children: node.children, status: 'loaded' };
+  }
+  const entry = cache.get(node.id);
+  if (!entry) return { children: null, status: 'idle' };
+  if (entry.status === 'loaded') {
+    return { children: entry.children, status: 'loaded' };
+  }
+  return { children: null, status: entry.status, error: entry.error };
+};

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

@@ -0,0 +1,42 @@
+'use client';
+
+import type { TreeNode } from '../types';
+
+export 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} />
+ */
+export function createDemoTree({
+  depth = 3,
+  breadth = 4,
+  rootPrefix = 'node',
+}: {
+  depth?: number;
+  breadth?: number;
+  rootPrefix?: string;
+} = {}): TreeNode<DemoNode>[] {
+  const make = (id: string, name: string, level: number): TreeNode<DemoNode> => {
+    if (level >= depth) {
+      return { id, data: { name } };
+    }
+    const children: TreeNode<DemoNode>[] = [];
+    for (let i = 0; i < breadth; i++) {
+      const childId = `${id}/${i}`;
+      children.push(make(childId, `${name}-${i}`, level + 1));
+    }
+    return { id, data: { name }, children };
+  };
+
+  const roots: TreeNode<DemoNode>[] = [];
+  for (let i = 0; i < breadth; i++) {
+    roots.push(make(`${rootPrefix}-${i}`, `${rootPrefix} ${i}`, 1));
+  }
+  return roots;
+}

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

@@ -0,0 +1,51 @@
+'use client';
+
+import type { FlatRow, TreeItemId, TreeNode } from '../types';
+import { resolveChildren, type ChildCache } from './childCache';
+
+export interface FlattenInput<T> {
+  roots: TreeNode<T>[];
+  expandedIds: ReadonlySet<TreeItemId>;
+  cache: ChildCache<T>;
+}
+
+const isNodeFolder = <T>(node: TreeNode<T>): boolean => {
+  if (typeof node.isFolder === 'boolean') return node.isFolder;
+  return Array.isArray(node.children);
+};
+
+/**
+ * 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.
+ */
+export function flattenTree<T>({ roots, expandedIds, cache }: FlattenInput<T>): FlatRow<T>[] {
+  const out: FlatRow<T>[] = [];
+
+  const walk = (nodes: TreeNode<T>[], level: number, parentId: TreeItemId | null) => {
+    for (const node of nodes) {
+      const isFolder = isNodeFolder(node);
+      const isExpanded = expandedIds.has(node.id);
+      const resolved = isFolder ? resolveChildren(cache, node) : { children: [], status: 'loaded' as const };
+
+      out.push({
+        node,
+        level,
+        parentId,
+        isFolder,
+        isExpanded,
+        isLoading: resolved.status === 'loading',
+        hasError: resolved.status === 'error',
+      });
+
+      if (isFolder && isExpanded && resolved.children) {
+        walk(resolved.children, level + 1, node.id);
+      }
+    }
+  };
+
+  walk(roots, 0, null);
+  return out;
+}

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

@@ -0,0 +1,24 @@
+'use client';
+
+export { createChildCache, getEntry, resolveChildren } from './childCache';
+export type { ChildCache, ChildEntry, ChildEntryStatus } from './childCache';
+export { flattenTree } from './flatten';
+export type { FlattenInput } from './flatten';
+export { loadTreeState, saveTreeState, clearTreeState } from './persist';
+export type { PersistedTreeState } from './persist';
+export { createDemoTree } from './createDemoTree';
+export type { DemoNode } from './createDemoTree';
+export {
+  DEFAULT_TREE_APPEARANCE,
+  resolveAppearance,
+  appearanceToStyle,
+  radiusClass,
+  rowStateClasses,
+} from './appearance';
+export type {
+  TreeAppearance,
+  ResolvedAppearance,
+  TreeDensity,
+  TreeAccentIntensity,
+  TreeRadius,
+} from './appearance';

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

@@ -0,0 +1,62 @@
+'use client';
+
+import type { TreeItemId } from '../types';
+
+const KEY_PREFIX = '@djangocfg/tree:';
+const VERSION = 1;
+
+export interface PersistedTreeState {
+  expandedItems: TreeItemId[];
+  selectedItems: TreeItemId[];
+}
+
+interface PersistedShape extends PersistedTreeState {
+  version: number;
+}
+
+function safeStorage(): Storage | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function loadTreeState(key: string): PersistedTreeState | null {
+  const storage = safeStorage();
+  if (!storage) return null;
+  try {
+    const raw = storage.getItem(KEY_PREFIX + key);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<PersistedShape>;
+    if (parsed.version !== VERSION) return null;
+    return {
+      expandedItems: Array.isArray(parsed.expandedItems) ? parsed.expandedItems : [],
+      selectedItems: Array.isArray(parsed.selectedItems) ? parsed.selectedItems : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function saveTreeState(key: string, state: PersistedTreeState): void {
+  const storage = safeStorage();
+  if (!storage) return;
+  try {
+    const payload: PersistedShape = { ...state, version: VERSION };
+    storage.setItem(KEY_PREFIX + key, JSON.stringify(payload));
+  } catch {
+    /* quota / serialization — best-effort persistence */
+  }
+}
+
+export function clearTreeState(key: string): void {
+  const storage = safeStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(KEY_PREFIX + key);
+  } catch {
+    /* ignore */
+  }
+}

package/src/tools/Tree/hooks/index.ts

@@ -0,0 +1,6 @@
+'use client';
+
+export { useTreeTypeAhead } from './useTreeTypeAhead';
+export type { UseTreeTypeAheadOptions } from './useTreeTypeAhead';
+export { useTreeKeyboard } from './useTreeKeyboard';
+export type { UseTreeKeyboardOptions } from './useTreeKeyboard';

package/src/tools/Tree/hooks/useTreeKeyboard.ts

@@ -0,0 +1,171 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+import { useHotkey } from '@djangocfg/ui-core/hooks';
+
+import type { FlatRow, TreeItemId } from '../types';
+
+export 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;
+}
+
+export 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
+ *  - 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
+ *
+ * Built on `useHotkey` (react-hotkeys-hook) — focus gating is automatic; no
+ * manual `addEventListener` or `data-scope` juggling.
+ */
+export function useTreeKeyboard<T>({
+  rows,
+  focusedId,
+  enabled = true,
+  onFocus,
+  onSelect,
+  onActivate,
+  onExpand,
+  onCollapse,
+  onClearSelection,
+}: UseTreeKeyboardOptions<T>): UseTreeKeyboardReturn {
+  // Keep latest values in refs so the callbacks below stay stable across
+  // renders — react-hotkeys-hook re-binds on dep change otherwise.
+  const rowsRef = useRef(rows);
+  const focusedIdRef = useRef(focusedId);
+  rowsRef.current = rows;
+  focusedIdRef.current = focusedId;
+
+  const getCurrent = () => {
+    const r = rowsRef.current;
+    const id = focusedIdRef.current;
+    const idx = id ? r.findIndex((x) => x.node.id === id) : -1;
+    return { rows: r, idx, current: idx >= 0 ? r[idx] : null };
+  };
+
+  const refDown = useHotkey(
+    'down',
+    () => {
+      const { rows: r, idx } = getCurrent();
+      if (r.length === 0) return;
+      const next = r[Math.min(idx + 1, r.length - 1)] ?? r[0];
+      onFocus(next.node.id);
+    },
+    { enabled, preventDefault: true, description: 'Next row' },
+  );
+
+  const refUp = useHotkey(
+    'up',
+    () => {
+      const { rows: r, idx } = getCurrent();
+      if (r.length === 0) return;
+      const prev = r[Math.max(idx - 1, 0)] ?? r[0];
+      onFocus(prev.node.id);
+    },
+    { enabled, preventDefault: true, description: 'Previous row' },
+  );
+
+  const refHome = useHotkey(
+    'home',
+    () => {
+      const { rows: r } = getCurrent();
+      if (r.length === 0) return;
+      onFocus(r[0].node.id);
+    },
+    { enabled, preventDefault: true, description: 'First row' },
+  );
+
+  const refEnd = useHotkey(
+    'end',
+    () => {
+      const { rows: r } = getCurrent();
+      if (r.length === 0) return;
+      onFocus(r[r.length - 1].node.id);
+    },
+    { enabled, preventDefault: true, description: 'Last row' },
+  );
+
+  const refRight = useHotkey(
+    'right',
+    () => {
+      const { rows: r, idx, current } = getCurrent();
+      if (!current) return;
+      if (current.isFolder && !current.isExpanded) {
+        onExpand(current.node.id);
+      } else if (current.isFolder && current.isExpanded) {
+        const next = r[idx + 1];
+        if (next) onFocus(next.node.id);
+      }
+    },
+    { enabled, preventDefault: true, description: 'Expand / first child' },
+  );
+
+  const refLeft = useHotkey(
+    'left',
+    () => {
+      const { current } = getCurrent();
+      if (!current) return;
+      if (current.isFolder && current.isExpanded) {
+        onCollapse(current.node.id);
+      } else if (current.parentId) {
+        onFocus(current.parentId);
+      }
+    },
+    { enabled, preventDefault: true, description: 'Collapse / parent' },
+  );
+
+  const refActivate = useHotkey(
+    ['enter', 'space'],
+    () => {
+      const { current } = getCurrent();
+      if (!current) return;
+      onSelect(current.node.id);
+      if (current.isFolder) {
+        if (current.isExpanded) onCollapse(current.node.id);
+        else onExpand(current.node.id);
+      } else {
+        onActivate(current.node.id);
+      }
+    },
+    { enabled, preventDefault: true, description: 'Activate / toggle' },
+  );
+
+  const refEscape = useHotkey(
+    'escape',
+    () => onClearSelection(),
+    { enabled, preventDefault: true, description: 'Clear selection' },
+  );
+
+  const ref = useCallback(
+    (instance: HTMLElement | null) => {
+      refDown(instance);
+      refUp(instance);
+      refHome(instance);
+      refEnd(instance);
+      refRight(instance);
+      refLeft(instance);
+      refActivate(instance);
+      refEscape(instance);
+    },
+    [refDown, refUp, refHome, refEnd, refRight, refLeft, refActivate, refEscape],
+  );
+
+  return { ref };
+}

package/src/tools/Tree/hooks/useTreeTypeAhead.ts

@@ -0,0 +1,100 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+import type { FlatRow, TreeNode } from '../types';
+
+const FLUSH_MS = 600;
+
+export interface UseTreeTypeAheadOptions<T> {
+  /** Visible flat rows in render order. */
+  rows: FlatRow<T>[];
+  /** How to read the displayed name of a node (matched case-insensitively). */
+  getItemName: (node: TreeNode<T>) => string;
+  /** Element receiving keydown events. */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Called with the matched node id so the consumer can focus / scroll. */
+  onMatch: (id: string) => void;
+  /** Disable without removing the call site. */
+  enabled?: boolean;
+}
+
+/**
+ * Type-ahead jump (Finder / VSCode style).
+ *
+ * Builds a rolling buffer of printable keys (within ~600 ms of each other)
+ * and notifies the consumer of the first row whose name starts with that
+ * prefix. Resets on Esc / Enter / navigation keys / timeout.
+ */
+export function useTreeTypeAhead<T>({
+  rows,
+  getItemName,
+  containerRef,
+  onMatch,
+  enabled = true,
+}: UseTreeTypeAheadOptions<T>) {
+  const bufferRef = useRef('');
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const rowsRef = useRef(rows);
+  const getNameRef = useRef(getItemName);
+  const onMatchRef = useRef(onMatch);
+  rowsRef.current = rows;
+  getNameRef.current = getItemName;
+  onMatchRef.current = onMatch;
+
+  useEffect(() => {
+    if (!enabled) return;
+    const target = containerRef.current;
+    if (!target) return;
+
+    const reset = () => {
+      bufferRef.current = '';
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+
+    const handler = (e: KeyboardEvent) => {
+      const tag = (e.target as HTMLElement | null)?.tagName;
+      if (tag === 'INPUT' || tag === 'TEXTAREA') return;
+      if ((e.target as HTMLElement | null)?.isContentEditable) return;
+      if (e.metaKey || e.ctrlKey || e.altKey) return;
+
+      if (
+        e.key === 'Escape' ||
+        e.key === 'Enter' ||
+        e.key === 'Tab' ||
+        e.key.startsWith('Arrow') ||
+        e.key === 'Home' ||
+        e.key === 'End' ||
+        e.key === 'PageUp' ||
+        e.key === 'PageDown'
+      ) {
+        reset();
+        return;
+      }
+
+      if (e.key.length !== 1) return;
+
+      bufferRef.current += e.key.toLowerCase();
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(reset, FLUSH_MS);
+
+      const prefix = bufferRef.current;
+      const hit = rowsRef.current.find((row) =>
+        getNameRef.current(row.node).toLowerCase().startsWith(prefix),
+      );
+      if (hit) {
+        e.preventDefault();
+        onMatchRef.current(hit.node.id);
+      }
+    };
+
+    target.addEventListener('keydown', handler);
+    return () => {
+      target.removeEventListener('keydown', handler);
+      reset();
+    };
+  }, [containerRef, enabled]);
+}