Hierarchy Construction

/**
 * Constructs a root node from hierarchical data
 * @param data - The root data object
 * @param children - Optional accessor function to get children array
 * @returns Root node of the hierarchy
 */
function hierarchy(data, children);

import { hierarchy } from "d3-hierarchy";

// Basic usage with standard 'children' property
const data = {
  name: "root",
  children: [
    { name: "child1" },
    { name: "child2", children: [{ name: "grandchild" }] }
  ]
};

const root = hierarchy(data);
console.log(root.children.length); // 2

// Custom children accessor
const customData = {
  name: "root",
  items: [{ name: "child1" }, { name: "child2" }]
};

const root2 = hierarchy(customData, d => d.items);

// Working with Map data
const mapData = new Map([
  ["root", new Map([
    ["child1", null],
    ["child2", new Map([["grandchild", null]])]
  ])]
]);

const root3 = hierarchy(mapData);

/**
 * Creates a stratify function for tabular data conversion  
 * @returns Stratify function with configuration methods
 */
function stratify();

interface StratifyFunction {
  /** Convert flat data array to hierarchy */
  (data: any[]): Node;
  /** Get/set the id accessor function */
  id(accessor?: (d: any, i: number, data: any[]) => string): StratifyFunction | Function;
  /** Get/set the parentId accessor function */  
  parentId(accessor?: (d: any, i: number, data: any[]) => string): StratifyFunction | Function;
  /** Get/set the path accessor function for path-based hierarchies */
  path(accessor?: (d: any, i: number, data: any[]) => string): StratifyFunction | Function;
}

import { stratify } from "d3-hierarchy";

// Basic stratify with id/parentId
const flatData = [
  { id: "root", parentId: null, name: "Root" },
  { id: "child1", parentId: "root", name: "Child 1" },
  { id: "child2", parentId: "root", name: "Child 2" },
  { id: "grandchild", parentId: "child2", name: "Grandchild" }
];

const stratifyFunc = stratify()
  .id(d => d.id)
  .parentId(d => d.parentId);

const root = stratifyFunc(flatData);
console.log(root.children.length); // 2

// Path-based stratification
const pathData = [
  { path: "/", name: "Root" },
  { path: "/docs", name: "Documentation" },
  { path: "/docs/api", name: "API Reference" },
  { path: "/src", name: "Source Code" }
];

const pathStratify = stratify()
  .path(d => d.path);

const pathRoot = pathStratify(pathData);

// Custom accessor functions
const customData = [
  { uid: 1, manager: null, employee: "CEO" },
  { uid: 2, manager: 1, employee: "CTO" }, 
  { uid: 3, manager: 1, employee: "CFO" },
  { uid: 4, manager: 2, employee: "Engineer" }
];

const customStratify = stratify()
  .id(d => d.uid)
  .parentId(d => d.manager);

const orgChart = customStratify(customData);

// Throws "missing: parentId" if parent reference doesn't exist
// Throws "ambiguous: id" if multiple nodes have same id  
// Throws "multiple roots" if more than one root node found
// Throws "no root" if no root node found
// Throws "cycle" if circular references detected

try {
  const root = stratifyFunc(invalidData);
} catch (error) {
  console.error("Hierarchy creation failed:", error.message);
}

/**
 * Default children accessor - returns d.children
 * @param d - Data object
 * @returns Array of children or null/undefined
 */
function defaultChildren(d) {
  return d.children;
}

// For nested arrays
const arrayData = [
  "root", 
  [
    ["child1"],
    ["child2", [["grandchild"]]]
  ]
];

const root = hierarchy(arrayData, d => Array.isArray(d) ? d.slice(1) : null);

// For object with custom property names
const customData = {
  title: "root",
  subitems: [
    { title: "child1" },
    { title: "child2", subitems: [{ title: "grandchild" }] }
  ]
};

const root2 = hierarchy(customData, d => d.subitems);