@djangocfg/ui-tools 2.1.314 → 2.1.315

package/src/tools/Tree/index.tsx

@@ -0,0 +1,99 @@
+'use client';
+
+/**
+ * Decomposed shadcn-style tree component.
+ *
+ * Two usage patterns:
+ *
+ *   1) High-level (most cases):
+ *      <TreeRoot data={...} getItemName={...} onSelectionChange={...} />
+ *
+ *   2) Composition (full control):
+ *      <TreeProvider data={...} getItemName={...}>
+ *        <TreeSearchInput />
+ *        <TreeContent />
+ *      </TreeProvider>
+ */
+
+export { TreeRoot, TreeRoot as Tree, default as default } from './TreeRoot';
+
+export {
+  TreeProvider,
+  useTreeContext,
+  useTreeLabels,
+  useTreeRows,
+  useTreeSelection,
+  useTreeExpansion,
+  useTreeFocus,
+  useTreeSearch,
+  useTreeActions,
+} from './context';
+export type { TreeProviderProps, TreeContextValue } from './context';
+
+export { useTreeTypeAhead, useTreeKeyboard } from './hooks';
+export type { UseTreeTypeAheadOptions, UseTreeKeyboardOptions } from './hooks';
+
+export {
+  TreeContent,
+  TreeRow,
+  TreeChevron,
+  TreeIcon,
+  TreeLabel,
+  TreeSearchInput,
+  TreeEmpty,
+  TreeSkeleton,
+  TreeError,
+  TreeIndentGuides,
+} from './components';
+export type {
+  TreeContentProps,
+  TreeRowProps,
+  TreeChevronProps,
+  TreeIconProps,
+  TreeLabelProps,
+  TreeSearchInputProps,
+  TreeEmptyProps,
+  TreeSkeletonProps,
+  TreeErrorProps,
+  TreeIndentGuidesProps,
+} from './components';
+
+export {
+  createChildCache,
+  resolveChildren,
+  flattenTree,
+  loadTreeState,
+  saveTreeState,
+  clearTreeState,
+  createDemoTree,
+  DEFAULT_TREE_APPEARANCE,
+  resolveAppearance,
+  appearanceToStyle,
+} from './data';
+export type {
+  ChildCache,
+  ChildEntry,
+  ChildEntryStatus,
+  FlattenInput,
+  PersistedTreeState,
+  DemoNode,
+  TreeAppearance,
+  ResolvedAppearance,
+  TreeDensity,
+  TreeAccentIntensity,
+  TreeRadius,
+} from './data';
+
+export { DEFAULT_TREE_LABELS } from './types';
+export type {
+  TreeRootProps,
+  TreeNode,
+  TreeItemId,
+  TreeLabels,
+  TreeSelectionMode,
+  TreeRowRenderProps,
+  TreeRowSlot,
+  TreeContextMenuSlot,
+  TreeLoadChildren,
+  FlatRow,
+} from './types';

package/src/tools/Tree/lazy.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import { createLazyComponent, LoadingFallback } from '../../components/lazy-wrapper';
+import type { TreeRootProps } from './types';
+
+export const LazyTree = createLazyComponent<TreeRootProps<unknown>>(
+  () => import('./TreeRoot'),
+  {
+    displayName: 'LazyTree',
+    fallback: <LoadingFallback minHeight={200} text="Loading tree…" />,
+  },
+);
+
+export type { TreeRootProps };

package/src/tools/Tree/types.ts

@@ -0,0 +1,136 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import type { TreeAppearance } from './data/appearance';
+
+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;
+}
+
+export interface TreeLabels {
+  loading: string;
+  empty: string;
+  error: string;
+  searchPlaceholder: string;
+  searchMatches: (count: number) => string;
+  ariaLabel: 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',
+};
+
+export type TreeSelectionMode = 'none' | 'single' | 'multiple';
+
+/**
+ * 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>[]>;
+
+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;
+
+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;
+  /** 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;
+  /** Enter / dblclick on a node. */
+  onActivate?: (node: TreeNode<T>) => void;
+
+  /** 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;
+
+  /** 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>;
+
+  /** 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;
+
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+/** Internal flat-row representation used by the renderer + keyboard nav. */
+export interface FlatRow<T> {
+  node: TreeNode<T>;
+  level: number;
+  parentId: TreeItemId | null;
+  isFolder: boolean;
+  isExpanded: boolean;
+  isLoading: boolean;
+  hasError: boolean;
+}

package/src/tools/index.ts

@@ -162,6 +162,81 @@ export type {
   MentionMarkdownRenderer,
 } from './MarkdownEditor';
 
+// Export Tree (decomposed shadcn-style tree, our own engine)
+export {
+  TreeRoot,
+  Tree,
+  TreeProvider,
+  useTreeContext,
+  useTreeLabels,
+  useTreeRows,
+  useTreeSelection,
+  useTreeExpansion,
+  useTreeFocus,
+  useTreeSearch,
+  useTreeActions,
+  useTreeTypeAhead,
+  useTreeKeyboard,
+  TreeContent,
+  TreeRow,
+  TreeChevron,
+  TreeIcon,
+  TreeLabel,
+  TreeSearchInput,
+  TreeEmpty,
+  TreeSkeleton,
+  TreeError,
+  TreeIndentGuides,
+  createChildCache,
+  resolveChildren,
+  flattenTree,
+  loadTreeState,
+  saveTreeState,
+  clearTreeState,
+  createDemoTree,
+  DEFAULT_TREE_LABELS,
+  DEFAULT_TREE_APPEARANCE,
+  resolveAppearance,
+  appearanceToStyle,
+} from './Tree';
+export type {
+  TreeRootProps,
+  TreeProviderProps,
+  TreeContextValue,
+  TreeContextMenuSlot,
+  TreeContentProps,
+  TreeRowProps,
+  TreeChevronProps,
+  TreeIconProps,
+  TreeLabelProps,
+  TreeSearchInputProps,
+  TreeEmptyProps,
+  TreeSkeletonProps,
+  TreeErrorProps,
+  TreeIndentGuidesProps,
+  TreeNode,
+  TreeItemId,
+  TreeLabels,
+  TreeSelectionMode,
+  TreeRowRenderProps,
+  TreeRowSlot,
+  TreeLoadChildren,
+  FlatRow,
+  ChildCache,
+  ChildEntry,
+  ChildEntryStatus,
+  FlattenInput,
+  PersistedTreeState,
+  UseTreeTypeAheadOptions,
+  UseTreeKeyboardOptions,
+  DemoNode,
+  TreeAppearance,
+  ResolvedAppearance,
+  TreeDensity,
+  TreeAccentIntensity,
+  TreeRadius,
+} from './Tree';
+
 // Export Media Cache Store
 export {
   useMediaCacheStore,