@monolith-forensics/monolith-ui 1.5.1 → 1.5.2-dev.0

package/dist/Table/StateStorage.d.ts

@@ -11,6 +11,8 @@ type GetSearchStateFn = (key: string) => string;
 type SetSearchStateFn = (key: string, value: string) => void;
 type GetFilterStateFn = (key: string) => Query | undefined;
 type SetFilterStateFn = (key: string, value?: Query | null) => void;
+type GetExpandedKeysFn = (key: string) => string[] | undefined;
+type SetExpandedKeysFn = (key: string, value: string[]) => void;
 declare const StateStorage: {
     getTableState: GetTableStateFn;
     getColumnState: GetColumnStateFn;
@@ -23,5 +25,7 @@ declare const StateStorage: {
     setSearchState: SetSearchStateFn;
     getFilterState: GetFilterStateFn;
     setFilterState: SetFilterStateFn;
+    getExpandedKeys: GetExpandedKeysFn;
+    setExpandedKeys: SetExpandedKeysFn;
 };
 export default StateStorage;

package/dist/Table/StateStorage.js

@@ -82,6 +82,17 @@ const setFilterState = (key, value) => {
     const newState = Object.assign(Object.assign({}, previousState), { filterState: value });
     set(key, newState);
 };
+const getExpandedKeys = (key) => {
+    const data = getTableState(key);
+    return data.expandedKeys;
+};
+const setExpandedKeys = (key, value) => {
+    // get previous state
+    const previousState = getTableState(key);
+    // merge previous state with new state
+    const newState = Object.assign(Object.assign({}, previousState), { expandedKeys: value });
+    set(key, newState);
+};
 const StateStorage = {
     getTableState,
     getColumnState,
@@ -94,5 +105,7 @@ const StateStorage = {
     setSearchState,
     getFilterState,
     setFilterState,
+    getExpandedKeys,
+    setExpandedKeys,
 };
 export default StateStorage;

package/dist/Table/Table.js

@@ -22,6 +22,7 @@ import TableMenu from "./TableMenu";
 import useTable from "./useTable";
 import LoadingIndicator from "./LoadingIndicator";
 import styled from "styled-components";
+import TableDefaults from "./TableDefaults";
 const StyledTableContainer = styled.div `
   display: flex;
   flex-direction: column;
@@ -40,8 +41,20 @@ const TableContent = ({ children, }) => {
                 }, ref: tableElement, "data-compact": compactState, children: [_jsx(LoadingIndicator, { visible: loading }), _jsx(TableHeader, { headerRowElm: headerRowElm }), visibleColumnCount === 0 && _jsx("div", { children: "No columns visible" }), virtualized === true ? (_jsx(VirtualizedRows, { tableDimensions: tableDimensions, targetElm: targetElm, listElm: listElm, rowHeight: rowHeight, headerRowHeight: headerRowHeight })) : (_jsx(StaticRows, { targetElm: targetElm, listElm: listElm }))] })] }));
 };
 export const Table = (_a) => {
-    var { data, columnProps, children } = _a, props = __rest(_a, ["data", "columnProps", "children"]) // pass through props straight to table context
+    var { data, columnProps, children, treeOptions } = _a, props = __rest(_a, ["data", "columnProps", "children", "treeOptions"]) // pass through props straight to table context
     ;
+    const resolvedTreeOptions = useMemo(() => {
+        var _a, _b, _c, _d, _e, _f;
+        return ({
+            enabled: (_a = treeOptions === null || treeOptions === void 0 ? void 0 : treeOptions.enabled) !== null && _a !== void 0 ? _a : false,
+            mode: (_b = treeOptions === null || treeOptions === void 0 ? void 0 : treeOptions.mode) !== null && _b !== void 0 ? _b : TableDefaults.tree.defaultMode,
+            childrenField: (_c = treeOptions === null || treeOptions === void 0 ? void 0 : treeOptions.childrenField) !== null && _c !== void 0 ? _c : TableDefaults.tree.defaultChildrenField,
+            parentIdField: (_d = treeOptions === null || treeOptions === void 0 ? void 0 : treeOptions.parentIdField) !== null && _d !== void 0 ? _d : TableDefaults.tree.defaultParentIdField,
+            idField: treeOptions === null || treeOptions === void 0 ? void 0 : treeOptions.idField,
+            indentPx: (_e = treeOptions === null || treeOptions === void 0 ? void 0 : treeOptions.indentPx) !== null && _e !== void 0 ? _e : TableDefaults.tree.indentPx,
+            autoExpandOnMatch: (_f = treeOptions === null || treeOptions === void 0 ? void 0 : treeOptions.autoExpandOnMatch) !== null && _f !== void 0 ? _f : true,
+        });
+    }, [treeOptions]);
     const tableElement = useRef(null);
     const targetElm = useRef(null);
     const listElm = useRef(null);
@@ -113,18 +126,153 @@ export const Table = (_a) => {
     // Uses a WeakMap so entries are automatically garbage collected
     // when their corresponding row objects are no longer referenced.
     const uuidCache = useRef(new WeakMap());
-    // Augment each row with a stable __key (UUID) and __index.
-    // The WeakMap ensures that the same row object always receives
-    // the same UUID across re-renders, preventing unnecessary DOM
-    // reconciliation. useMemo preserves referential stability of
-    // the output array when the data reference hasn't changed.
-    const __data = useMemo(() => data === null || data === void 0 ? void 0 : data.map((d, i) => {
-        let key = uuidCache.current.get(d);
+    const getOrAssignKey = (row) => {
+        let key = uuidCache.current.get(row);
         if (!key) {
             key = shortUUID.uuid();
-            uuidCache.current.set(d, key);
+            uuidCache.current.set(row, key);
+        }
+        return key;
+    };
+    // Augment each row with stable metadata. When tree mode is disabled,
+    // produces a flat 1:1 mapping with __key and __index. When enabled,
+    // walks the input (nested or flat) into a flat depth-first array
+    // and adds tree metadata (__level, __parentKey, __hasChildren, __childKeys).
+    const { rows: __data, treeMeta } = useMemo(() => {
+        const parentKeyMap = new Map();
+        const childrenKeyMap = new Map();
+        const expandableKeys = [];
+        if (!data) {
+            return {
+                rows: [],
+                treeMeta: { parentKeyMap, childrenKeyMap, expandableKeys },
+            };
+        }
+        if (!resolvedTreeOptions.enabled) {
+            const rows = data.map((d, i) => (Object.assign(Object.assign({}, d), { __key: getOrAssignKey(d), __index: i })));
+            return {
+                rows,
+                treeMeta: { parentKeyMap, childrenKeyMap, expandableKeys },
+            };
         }
-        return Object.assign(Object.assign({}, d), { __key: key, __index: i });
-    }), [data]);
-    return (_jsx(TableProvider, Object.assign({ columns: columnProps, data: __data, tableElement: tableElement, headerRowElm: headerRowElm, tableDimensions: tableDimensions, targetElm: targetElm, listElm: listElm }, props, { children: _jsx(TableContent, { children: children }) })));
+        const rows = [];
+        let counter = 0;
+        if (resolvedTreeOptions.mode === "nested") {
+            const childrenField = resolvedTreeOptions.childrenField;
+            const walk = (node, level, parentKey) => {
+                const key = getOrAssignKey(node);
+                const rawChildren = node === null || node === void 0 ? void 0 : node[childrenField];
+                const children = Array.isArray(rawChildren) ? rawChildren : [];
+                const childKeys = children.map((c) => getOrAssignKey(c));
+                // Strip the nested children field from the augmented copy to avoid
+                // memory bloat and prevent accidental iteration of the raw tree.
+                const _a = node, _b = childrenField, _stripped = _a[_b], rest = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+                const augmented = Object.assign(Object.assign({}, rest), { __key: key, __index: counter++, __level: level, __parentKey: parentKey, __hasChildren: children.length > 0, __childKeys: childKeys });
+                rows.push(augmented);
+                parentKeyMap.set(key, parentKey);
+                if (children.length > 0) {
+                    childrenKeyMap.set(key, childKeys);
+                    expandableKeys.push(key);
+                }
+                for (const child of children) {
+                    walk(child, level + 1, key);
+                }
+            };
+            const rootKeys = [];
+            for (const root of data) {
+                rootKeys.push(getOrAssignKey(root));
+                walk(root, 0, undefined);
+            }
+            childrenKeyMap.set(undefined, rootKeys);
+        }
+        else {
+            // flat mode
+            const idField = resolvedTreeOptions.idField || props.keyField;
+            if (!idField) {
+                throw new Error('Table treeOptions.mode="flat" requires either treeOptions.idField or keyField to be set so the table can resolve parent-child relationships against a stable id.');
+            }
+            const parentIdField = resolvedTreeOptions.parentIdField;
+            // Pass 1: assign __key, build idToKey
+            const idToKey = new Map();
+            const idToRow = new Map();
+            for (const d of data) {
+                const id = d === null || d === void 0 ? void 0 : d[idField];
+                if (id === undefined || id === null)
+                    continue;
+                idToKey.set(id, getOrAssignKey(d));
+                idToRow.set(id, d);
+            }
+            // Pass 2: build parent->children id map. Roots = parentId null/undefined
+            // OR parentId points at a non-existent row.
+            const parentToChildIds = new Map();
+            const rootIds = [];
+            let warnedOrphan = false;
+            for (const d of data) {
+                const id = d === null || d === void 0 ? void 0 : d[idField];
+                if (id === undefined || id === null)
+                    continue;
+                const parentId = d === null || d === void 0 ? void 0 : d[parentIdField];
+                if (parentId === undefined || parentId === null) {
+                    rootIds.push(id);
+                    continue;
+                }
+                if (!idToRow.has(parentId)) {
+                    if (!warnedOrphan) {
+                        // eslint-disable-next-line no-console
+                        console.warn(`Table tree (flat mode): row id "${id}" references missing parentId "${parentId}"; treating as root.`);
+                        warnedOrphan = true;
+                    }
+                    rootIds.push(id);
+                    continue;
+                }
+                if (!parentToChildIds.has(parentId))
+                    parentToChildIds.set(parentId, []);
+                parentToChildIds.get(parentId).push(id);
+            }
+            // Pass 3: DFS from roots with cycle detection
+            const visiting = new Set();
+            let warnedCycle = false;
+            const walkFlat = (id, level, parentKey) => {
+                if (visiting.has(id)) {
+                    if (!warnedCycle) {
+                        // eslint-disable-next-line no-console
+                        console.warn(`Table tree (flat mode): cycle detected at row id "${id}"; truncating subtree.`);
+                        warnedCycle = true;
+                    }
+                    return;
+                }
+                visiting.add(id);
+                const node = idToRow.get(id);
+                const key = idToKey.get(id);
+                const childIds = parentToChildIds.get(id) || [];
+                const childKeys = childIds
+                    .map((cid) => idToKey.get(cid))
+                    .filter((k) => !!k);
+                const augmented = Object.assign(Object.assign({}, node), { __key: key, __index: counter++, __level: level, __parentKey: parentKey, __hasChildren: childIds.length > 0, __childKeys: childKeys });
+                rows.push(augmented);
+                parentKeyMap.set(key, parentKey);
+                if (childIds.length > 0) {
+                    childrenKeyMap.set(key, childKeys);
+                    expandableKeys.push(key);
+                }
+                for (const cid of childIds) {
+                    walkFlat(cid, level + 1, key);
+                }
+                visiting.delete(id);
+            };
+            const rootKeys = [];
+            for (const id of rootIds) {
+                const k = idToKey.get(id);
+                if (k)
+                    rootKeys.push(k);
+                walkFlat(id, 0, undefined);
+            }
+            childrenKeyMap.set(undefined, rootKeys);
+        }
+        return {
+            rows,
+            treeMeta: { parentKeyMap, childrenKeyMap, expandableKeys },
+        };
+    }, [data, resolvedTreeOptions, props.keyField]);
+    return (_jsx(TableProvider, Object.assign({ columns: columnProps, data: __data, tableElement: tableElement, headerRowElm: headerRowElm, tableDimensions: tableDimensions, targetElm: targetElm, listElm: listElm, treeOptions: resolvedTreeOptions, treeMeta: treeMeta }, props, { children: _jsx(TableContent, { children: children }) })));
 };

package/dist/Table/TableComponents.d.ts

@@ -6,6 +6,16 @@ export declare const THR: import("styled-components/dist/types").IStyledComponen
 export declare const TD: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, TDProps>> & string;
 export declare const TH: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, keyof TDProps> & TDProps, never>> & string;
 export declare const InnerCellContent: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>> & string;
+export declare const TreeCellWrapper: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>> & string;
+export declare const TreeIndentSpacer: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {
+    $level: number;
+    $indentPx: number;
+}>> & string;
+export declare const TreeChevronButton: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, {
+    $expanded: boolean;
+}>> & string;
+export declare const TreeChevronPlaceholder: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>> & string;
+export declare const TreeCellContent: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>> & string;
 export declare const TableViewPort: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>> & string;
 export declare const TableListElement: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>> & string;
 export declare const TableWrapper: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>> & string;

package/dist/Table/TableComponents.js

@@ -115,6 +115,55 @@ export const InnerCellContent = styled.div `
   overflow: hidden;
   text-overflow: ellipsis;
 `;
+export const TreeCellWrapper = styled.div `
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  flex: 1 1 auto;
+  min-width: 0;
+  gap: 4px;
+`;
+export const TreeIndentSpacer = styled.div `
+  flex: 0 0 auto;
+  width: ${({ $level, $indentPx }) => $level * $indentPx}px;
+`;
+export const TreeChevronButton = styled.button `
+  flex: 0 0 auto;
+  width: 16px;
+  height: 16px;
+  padding: 0;
+  margin: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  color: ${({ theme }) => theme.palette.text.secondary};
+  transition: transform 120ms ease;
+  transform: rotate(${({ $expanded }) => ($expanded ? "90deg" : "0deg")});
+
+  &:hover {
+    color: ${({ theme }) => theme.palette.text.primary};
+  }
+
+  &:focus-visible {
+    outline: 1px solid ${({ theme }) => theme.palette.primary.main};
+    outline-offset: 1px;
+  }
+`;
+export const TreeChevronPlaceholder = styled.div `
+  flex: 0 0 auto;
+  width: 16px;
+  height: 16px;
+`;
+export const TreeCellContent = styled.div `
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`;
 export const TableViewPort = styled.div `
   display: flex;
   flex-direction: column;

package/dist/Table/TableDefaults.d.ts

@@ -21,5 +21,12 @@ declare const TableDefaults: {
         minWidth: number;
         maxWidth: number;
     };
+    tree: {
+        indentPx: number;
+        chevronWidth: number;
+        defaultMode: "nested";
+        defaultChildrenField: string;
+        defaultParentIdField: string;
+    };
 };
 export default TableDefaults;

package/dist/Table/TableDefaults.js

@@ -21,5 +21,12 @@ const TableDefaults = {
         minWidth: 35,
         maxWidth: 35,
     },
+    tree: {
+        indentPx: 16,
+        chevronWidth: 16,
+        defaultMode: "nested",
+        defaultChildrenField: "children",
+        defaultParentIdField: "parentId",
+    },
 };
 export default TableDefaults;

package/dist/Table/TableProvider.js

@@ -28,6 +28,27 @@ import { SelectionStatus } from "./enums";
 import moment from "moment";
 import { useControlled } from "../Utilities";
 import { exportTableToExcel } from "./Utils";
+const RESERVED_FIELDS = [
+    "__key",
+    "__index",
+    "__level",
+    "__parentKey",
+    "__hasChildren",
+    "__childKeys",
+];
+const EMPTY_TREE_META = {
+    parentKeyMap: new Map(),
+    childrenKeyMap: new Map(),
+    expandableKeys: [],
+};
+const DEFAULT_TREE_OPTIONS = {
+    enabled: false,
+    mode: "nested",
+    childrenField: "children",
+    parentIdField: "parentId",
+    indentPx: 16,
+    autoExpandOnMatch: true,
+};
 const calculateSelectionTotal = (selectionState, totalRecords, dataLength = 0) => {
     if (!selectionState) {
         return 0;
@@ -47,11 +68,21 @@ const calculateSelectionTotal = (selectionState, totalRecords, dataLength = 0) =
 };
 export const TableContext = createContext(null);
 const TableProvider = (_a) => {
-    var { children, columns, data, keyField, tableInstanceRef, stateStorage, tableMenuOptions, manualSorting, manualFiltering, manualSearch, manualExport, height, maxHeight, minHeight, focusedRowId, enableColumnResize, enableSorting, compact, totalRecords, onColumnStateChange, onColumnReorder, onColumnHeaderClick, onSort, onRowUpdated, tableElement, headerRowElm, tableDimensions, targetElm, listElm, defaultSelectionState, selectionState, onSelectionChange, defaultFilterState, filterState, onFilterChange } = _a, props = __rest(_a, ["children", "columns", "data", "keyField", "tableInstanceRef", "stateStorage", "tableMenuOptions", "manualSorting", "manualFiltering", "manualSearch", "manualExport", "height", "maxHeight", "minHeight", "focusedRowId", "enableColumnResize", "enableSorting", "compact", "totalRecords", "onColumnStateChange", "onColumnReorder", "onColumnHeaderClick", "onSort", "onRowUpdated", "tableElement", "headerRowElm", "tableDimensions", "targetElm", "listElm", "defaultSelectionState", "selectionState", "onSelectionChange", "defaultFilterState", "filterState", "onFilterChange"]);
+    var { children, columns, data, keyField, tableInstanceRef, stateStorage, tableMenuOptions, manualSorting, manualFiltering, manualSearch, manualExport, height, maxHeight, minHeight, focusedRowId, enableColumnResize, enableSorting, compact, totalRecords, onColumnStateChange, onColumnReorder, onColumnHeaderClick, onSort, onRowUpdated, tableElement, headerRowElm, tableDimensions, targetElm, listElm, defaultSelectionState, selectionState, onSelectionChange, defaultFilterState, filterState, onFilterChange, treeOptions, treeMeta, defaultExpandedKeys, expandedKeys, onExpandedChange } = _a, props = __rest(_a, ["children", "columns", "data", "keyField", "tableInstanceRef", "stateStorage", "tableMenuOptions", "manualSorting", "manualFiltering", "manualSearch", "manualExport", "height", "maxHeight", "minHeight", "focusedRowId", "enableColumnResize", "enableSorting", "compact", "totalRecords", "onColumnStateChange", "onColumnReorder", "onColumnHeaderClick", "onSort", "onRowUpdated", "tableElement", "headerRowElm", "tableDimensions", "targetElm", "listElm", "defaultSelectionState", "selectionState", "onSelectionChange", "defaultFilterState", "filterState", "onFilterChange", "treeOptions", "treeMeta", "defaultExpandedKeys", "expandedKeys", "onExpandedChange"]);
+    const _treeOptions = treeOptions || DEFAULT_TREE_OPTIONS;
+    const _treeMeta = treeMeta || EMPTY_TREE_META;
+    if (_treeOptions.enabled) {
+        if (RESERVED_FIELDS.includes(_treeOptions.childrenField)) {
+            throw new Error(`treeOptions.childrenField cannot be a reserved internal field: "${_treeOptions.childrenField}".`);
+        }
+        if (RESERVED_FIELDS.includes(_treeOptions.parentIdField)) {
+            throw new Error(`treeOptions.parentIdField cannot be a reserved internal field: "${_treeOptions.parentIdField}".`);
+        }
+    }
     const _columns = useMemo(() => columns
         .map((child, index) => {
-        if (child.dataField === "__key") {
-            throw new Error("dataField cannot be __key");
+        if (RESERVED_FIELDS.includes(child.dataField)) {
+            throw new Error(`dataField cannot be a reserved internal field: "${child.dataField}". Reserved: ${RESERVED_FIELDS.join(", ")}`);
         }
         // check for duplicate dataFields
         const dataFieldCount = columns.filter((col) => col.dataField === child.dataField).length;
@@ -70,7 +101,7 @@ const TableProvider = (_a) => {
             ? StateStorage.getTableState(stateStorage.key)
             : undefined;
     }, [stateStorage === null || stateStorage === void 0 ? void 0 : stateStorage.key]);
-    const { columnState: savedColumnState, selectionState: savedSelectionState, sortState: savedSortState, searchState: savedSearchState, filterState: savedFilterState, } = savedTableState || {};
+    const { columnState: savedColumnState, selectionState: savedSelectionState, sortState: savedSortState, searchState: savedSearchState, filterState: savedFilterState, expandedKeys: savedExpandedKeys, } = savedTableState || {};
     const [compactState, setCompactState] = useState(compact || false);
     const [columnState, setColumnState] = useState(syncColumnState(_columns, savedColumnState));
     const [search, setSearch] = useState(savedSearchState || "");
@@ -80,6 +111,8 @@ const TableProvider = (_a) => {
         rules: [],
     });
     const [sortState, setSortState] = useState(savedSortState);
+    const [_expandedKeys, _setExpandedKeys] = useControlled(expandedKeys, defaultExpandedKeys || savedExpandedKeys || []);
+    const expandedKeysSet = useMemo(() => new Set(_expandedKeys), [_expandedKeys]);
     const [_selectionState, _setSelectionState] = useControlled(selectionState, defaultSelectionState || {
         selectedRowKeys: (savedSelectionState === null || savedSelectionState === void 0 ? void 0 : savedSelectionState.selectedRowKeys) || [],
         excludedRowKeys: (savedSelectionState === null || savedSelectionState === void 0 ? void 0 : savedSelectionState.excludedRowKeys) || [],
@@ -227,58 +260,99 @@ const TableProvider = (_a) => {
             }
         }
     };
-    const sortData = (sortState) => {
-        // sort data
-        return data.sort((a, b) => {
-            if (sortState) {
-                const aValue = a[sortState.dataField];
-                const bValue = b[sortState.dataField];
-                const aIsEmpty = aValue === null || aValue === undefined;
-                const bIsEmpty = bValue === null || bValue === undefined;
-                // Treat empty values as the smallest values.
-                if (aIsEmpty && bIsEmpty) {
-                    return 0;
-                }
-                if (aIsEmpty || bIsEmpty) {
-                    if (sortState.dir === "asc") {
-                        return aIsEmpty ? -1 : 1;
-                    }
-                    if (sortState.dir === "desc") {
-                        return aIsEmpty ? 1 : -1;
-                    }
-                }
+    const compareRows = (a, b, sortState) => {
+        if (sortState) {
+            const aValue = a[sortState.dataField];
+            const bValue = b[sortState.dataField];
+            const aIsEmpty = aValue === null || aValue === undefined;
+            const bIsEmpty = bValue === null || bValue === undefined;
+            // Treat empty values as the smallest values.
+            if (aIsEmpty && bIsEmpty) {
+                return 0;
+            }
+            if (aIsEmpty || bIsEmpty) {
                 if (sortState.dir === "asc") {
-                    if (aValue < bValue) {
-                        return -1;
-                    }
-                    if (aValue > bValue) {
-                        return 1;
-                    }
-                    return 0;
+                    return aIsEmpty ? -1 : 1;
                 }
-                else if (sortState.dir === "desc") {
-                    if (aValue > bValue) {
-                        return -1;
-                    }
-                    if (aValue < bValue) {
-                        return 1;
-                    }
-                    return 0;
+                if (sortState.dir === "desc") {
+                    return aIsEmpty ? 1 : -1;
                 }
             }
-            // sort by __index
-            if (a.__index < b.__index) {
-                return -1;
+            if (sortState.dir === "asc") {
+                if (aValue < bValue)
+                    return -1;
+                if (aValue > bValue)
+                    return 1;
+                return 0;
             }
-            if (a.__index > b.__index) {
-                return 1;
+            else if (sortState.dir === "desc") {
+                if (aValue > bValue)
+                    return -1;
+                if (aValue < bValue)
+                    return 1;
+                return 0;
             }
-            return 0;
-        });
+        }
+        // sort by __index
+        if (a.__index < b.__index)
+            return -1;
+        if (a.__index > b.__index)
+            return 1;
+        return 0;
+    };
+    const sortData = (sortState) => {
+        if (!_treeOptions.enabled) {
+            // Flat data — sort in-place (preserves existing behavior).
+            return data.sort((a, b) => compareRows(a, b, sortState));
+        }
+        // Tree-aware sort: sort siblings only, then re-DFS to rebuild the
+        // flat order. Cross-parent sorting is never allowed in tree mode.
+        const byKey = new Map();
+        const childrenByParent = new Map();
+        for (const row of data) {
+            byKey.set(row.__key, row);
+            const pk = row.__parentKey;
+            if (!childrenByParent.has(pk))
+                childrenByParent.set(pk, []);
+            childrenByParent.get(pk).push(row);
+        }
+        for (const [, siblings] of childrenByParent) {
+            siblings.sort((a, b) => compareRows(a, b, sortState));
+        }
+        const result = [];
+        const walk = (parentKey) => {
+            const siblings = childrenByParent.get(parentKey);
+            if (!siblings)
+                return;
+            for (const row of siblings) {
+                result.push(row);
+                if (row.__hasChildren)
+                    walk(row.__key);
+            }
+        };
+        walk(undefined);
+        return result;
+    };
+    const collectAncestors = (rows) => {
+        const ancestorSet = new Set();
+        const byKey = new Map();
+        for (const r of data)
+            byKey.set(r.__key, r);
+        for (const row of rows) {
+            let parentKey = row.__parentKey;
+            while (parentKey) {
+                if (ancestorSet.has(parentKey))
+                    break;
+                ancestorSet.add(parentKey);
+                const parent = byKey.get(parentKey);
+                parentKey = parent === null || parent === void 0 ? void 0 : parent.__parentKey;
+            }
+        }
+        return ancestorSet;
     };
-    const searchData = (searchText) => {
+    const searchData = (rows, searchText) => {
         const columnKeys = columnState.map((col) => col.dataField);
-        return data.filter((row) => {
+        const matched = rows.filter((row) => {
             return columnKeys.some((key) => {
                 if (typeof row[key] === "string") {
                     return row[key].toLowerCase().includes(searchText.toLowerCase());
@@ -286,6 +360,16 @@ const TableProvider = (_a) => {
                 return false;
             });
         });
+        if (!_treeOptions.enabled) {
+            return { rows: matched, ancestorKeys: new Set() };
+        }
+        const ancestorKeys = collectAncestors(matched);
+        const visibleSet = new Set(matched.map((r) => r.__key));
+        ancestorKeys.forEach((k) => visibleSet.add(k));
+        return {
+            rows: rows.filter((r) => visibleSet.has(r.__key)),
+            ancestorKeys,
+        };
     };
     const rowMatchesRule = (row, rule) => {
         var _a, _b, _c, _d;
@@ -385,16 +469,26 @@ const TableProvider = (_a) => {
                 return true;
         }
     };
-    const filterData = (filter) => {
-        if (!data)
-            return [];
+    const filterData = (rows, filter) => {
+        if (!rows)
+            return { rows: [], ancestorKeys: new Set() };
         const { combinator, rules } = filter;
-        if (!combinator || !rules)
-            return data;
-        if (combinator === "or") {
-            return data.filter((row) => rules.some((rule) => rowMatchesRule(row, rule)));
+        if (!combinator || !rules || rules.length === 0) {
+            return { rows, ancestorKeys: new Set() };
         }
-        return data.filter((row) => rules.every((rule) => rowMatchesRule(row, rule)));
+        const matched = combinator === "or"
+            ? rows.filter((row) => rules.some((rule) => rowMatchesRule(row, rule)))
+            : rows.filter((row) => rules.every((rule) => rowMatchesRule(row, rule)));
+        if (!_treeOptions.enabled) {
+            return { rows: matched, ancestorKeys: new Set() };
+        }
+        const ancestorKeys = collectAncestors(matched);
+        const visibleSet = new Set(matched.map((r) => r.__key));
+        ancestorKeys.forEach((k) => visibleSet.add(k));
+        return {
+            rows: rows.filter((r) => visibleSet.has(r.__key)),
+            ancestorKeys,
+        };
     };
     const toggleColumnVisibility = (dataField) => {
         const newColumnState = columnState.map((col) => {
@@ -423,6 +517,47 @@ const TableProvider = (_a) => {
         const key = !!keyField ? row[keyField] : row.__key;
         return String(key);
     };
+    const firstVisibleDataField = useMemo(() => { var _a; return (_a = columnState.find((c) => c.visible !== false)) === null || _a === void 0 ? void 0 : _a.dataField; }, [columnState]);
+    const persistExpandedKeys = (next) => {
+        if ((stateStorage === null || stateStorage === void 0 ? void 0 : stateStorage.enabled) && (stateStorage === null || stateStorage === void 0 ? void 0 : stateStorage.type) === "localStorage") {
+            StateStorage.setExpandedKeys(stateStorage.key, next);
+        }
+    };
+    const updateExpandedKeys = (next) => {
+        _setExpandedKeys(next);
+        onExpandedChange === null || onExpandedChange === void 0 ? void 0 : onExpandedChange(next);
+        persistExpandedKeys(next);
+    };
+    const expandRow = (row) => {
+        var _a;
+        const key = (_a = row === null || row === void 0 ? void 0 : row.__key) !== null && _a !== void 0 ? _a : getRowKey(row);
+        if (expandedKeysSet.has(key))
+            return;
+        updateExpandedKeys([..._expandedKeys, key]);
+    };
+    const collapseRow = (row) => {
+        var _a;
+        const key = (_a = row === null || row === void 0 ? void 0 : row.__key) !== null && _a !== void 0 ? _a : getRowKey(row);
+        if (!expandedKeysSet.has(key))
+            return;
+        updateExpandedKeys(_expandedKeys.filter((k) => k !== key));
+    };
+    const toggleRowExpanded = (row) => {
+        var _a;
+        const key = (_a = row === null || row === void 0 ? void 0 : row.__key) !== null && _a !== void 0 ? _a : getRowKey(row);
+        if (expandedKeysSet.has(key)) {
+            updateExpandedKeys(_expandedKeys.filter((k) => k !== key));
+        }
+        else {
+            updateExpandedKeys([..._expandedKeys, key]);
+        }
+    };
+    const expandAllRows = () => {
+        updateExpandedKeys([..._treeMeta.expandableKeys]);
+    };
+    const collapseAllRows = () => {
+        updateExpandedKeys([]);
+    };
     const selectRow = (row) => {
         const key = getRowKey(row);
         const newSelectionState = {
@@ -560,6 +695,61 @@ const TableProvider = (_a) => {
         const key = getRowKey(row);
         return focusedRowId === key;
     };
+    const { _data, effectiveExpandedKeys } = useMemo(() => {
+        let processedData = data || [];
+        if (manualSorting !== true) {
+            processedData = sortData(sortState);
+        }
+        const autoExpandedSet = new Set();
+        if (manualFiltering !== true && _filterState) {
+            const result = filterData(processedData, _filterState);
+            processedData = result.rows;
+            if (_treeOptions.enabled && _treeOptions.autoExpandOnMatch) {
+                result.ancestorKeys.forEach((k) => autoExpandedSet.add(k));
+            }
+        }
+        if (manualSearch !== true && search) {
+            const result = searchData(processedData, search);
+            processedData = result.rows;
+            if (_treeOptions.enabled && _treeOptions.autoExpandOnMatch) {
+                result.ancestorKeys.forEach((k) => autoExpandedSet.add(k));
+            }
+        }
+        // Compute the effective expanded set: user expansion ∪ auto-expanded ancestors.
+        // Never mutates user's _expandedKeys.
+        const effective = new Set(expandedKeysSet);
+        autoExpandedSet.forEach((k) => effective.add(k));
+        // Final pass: drop rows whose ancestors are not in the effective set.
+        if (_treeOptions.enabled) {
+            const byKey = new Map();
+            for (const r of processedData)
+                byKey.set(r.__key, r);
+            processedData = processedData.filter((row) => {
+                let pk = row.__parentKey;
+                while (pk) {
+                    if (!effective.has(pk))
+                        return false;
+                    const parent = byKey.get(pk);
+                    pk = parent === null || parent === void 0 ? void 0 : parent.__parentKey;
+                }
+                return true;
+            });
+        }
+        return { _data: processedData, effectiveExpandedKeys: effective };
+    }, [
+        data,
+        columnState,
+        search,
+        sortState,
+        _filterState,
+        expandedKeysSet,
+        _treeOptions,
+    ]);
+    const isRowExpanded = (row) => {
+        var _a;
+        const key = (_a = row === null || row === void 0 ? void 0 : row.__key) !== null && _a !== void 0 ? _a : getRowKey(row);
+        return effectiveExpandedKeys.has(key);
+    };
     if (tableInstanceRef) {
         tableInstanceRef.current = {
             columnState,
@@ -576,6 +766,13 @@ const TableProvider = (_a) => {
             clearSelections,
             runSearch,
             clearSearch,
+            expandRow,
+            collapseRow,
+            toggleRowExpanded,
+            isRowExpanded,
+            expandAllRows,
+            collapseAllRows,
+            getExpandedRowKeys: () => [..._expandedKeys],
             getTableState: () => {
                 return {
                     columnState,
@@ -587,24 +784,12 @@ const TableProvider = (_a) => {
                     },
                     sortState,
                     searchState: search,
-                    _filterState,
+                    filterState: _filterState,
+                    expandedKeys: [..._expandedKeys],
                 };
             },
         };
     }
-    const _data = useMemo(() => {
-        let processedData = data; // create a new array to avoid mutating the original data
-        if (manualSorting !== true) {
-            processedData = sortData(sortState);
-        }
-        if (manualFiltering !== true && _filterState) {
-            processedData = filterData(_filterState);
-        }
-        if (manualSearch !== true && search) {
-            processedData = searchData(search);
-        }
-        return processedData;
-    }, [data, columnState, search, sortState, _filterState]);
     return (_jsx(TableContext.Provider, { value: Object.assign({ columnState,
             setColumnState,
             sortState, searchState: search, totalRecords,
@@ -631,6 +816,13 @@ const TableProvider = (_a) => {
             stateStorage, tableHeight: height, tableMaxHeight: maxHeight, tableMinHeight: minHeight, compact, tableElement: tableElement, headerRowElm: headerRowElm, tableDimensions: tableDimensions, targetElm: targetElm, listElm: listElm, enableColumnResize,
             onSelectionChange,
             onColumnStateChange,
-            onColumnReorder, onRowUpdated: onRowUpdated || (() => { }), tableMenuOptions, data: _data }, props), children: children }));
+            onColumnReorder, onRowUpdated: onRowUpdated || (() => { }), tableMenuOptions, data: _data, treeOptions: _treeOptions, firstVisibleDataField, expandedKeys: _expandedKeys, effectiveExpandedKeys,
+            isRowExpanded,
+            toggleRowExpanded,
+            expandRow,
+            collapseRow,
+            expandAllRows,
+            collapseAllRows,
+            onExpandedChange }, props), children: children }));
 };
 export default TableProvider;

package/dist/Table/TableRow.js

@@ -1,20 +1,21 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Maximize2Icon } from "lucide-react";
+import { ChevronRightIcon, Maximize2Icon } from "lucide-react";
 import ColumnResizer from "./ColumnResizer";
-import { InnerCellContent, TD, TR } from "./TableComponents";
+import { InnerCellContent, TD, TR, TreeCellContent, TreeCellWrapper, TreeChevronButton, TreeChevronPlaceholder, TreeIndentSpacer, } from "./TableComponents";
 import useTable from "./useTable";
 import ActionCell from "./ActionCell";
 import ActionButton from "./ActionButton";
 import CheckBox from "../CheckBox";
 import { LoadingCellIndicator } from "./LoadingCellIndicator";
 const TableRow = ({ rowData, loading, rowStyle }) => {
-    const { columnState, enableActionButton, onActionButtonClick, actionButtonIcon: Icon, enableSelection, selectRow, deselectRow, isRowSelected, isRowFocused, onRowUpdated, } = useTable();
+    const { columnState, enableActionButton, onActionButtonClick, actionButtonIcon: Icon, enableSelection, selectRow, deselectRow, isRowSelected, isRowFocused, onRowUpdated, treeOptions, firstVisibleDataField, isRowExpanded, toggleRowExpanded, } = useTable();
     const selected = isRowSelected(rowData);
     const focused = isRowFocused(rowData);
     const handleSelectionChange = (e) => {
         e === true ? selectRow(rowData) : deselectRow(rowData);
     };
     return (_jsxs(TR, { className: "mfui-tr", style: rowStyle, "data-key": rowData.__key, "data-selected": selected, "data-focused": focused, children: [enableSelection && (_jsx(ActionCell, { className: `mfui-td column-select`, children: _jsx(InnerCellContent, { className: "mfui inner-cell-content row-action", children: _jsx(CheckBox, { className: `mfui-checkbox`, value: selected, onChange: (e) => handleSelectionChange(e) }) }) })), enableActionButton && (_jsx(ActionCell, { className: `mfui-td column-action`, children: _jsx(InnerCellContent, { className: "mfui inner-cell-content row-action", children: _jsx(ActionButton, { variant: "subtle", onClick: () => onActionButtonClick === null || onActionButtonClick === void 0 ? void 0 : onActionButtonClick(rowData), children: Icon ? _jsx(Icon, { size: 14 }) : _jsx(Maximize2Icon, { size: 14 }) }) }) })), columnState.map((column, index) => {
+                var _a;
                 if (column.visible === false)
                     return null;
                 if (loading) {
@@ -24,16 +25,20 @@ const TableRow = ({ rowData, loading, rowStyle }) => {
                             flex: column.width ? "0 0 auto" : "1",
                         }, children: _jsx(LoadingCellIndicator, {}) }, index));
                 }
+                const cellBody = column.render
+                    ? column.render({ rowData, onRowUpdated })
+                    : rowData[column.dataField];
+                const isTreeColumn = (treeOptions === null || treeOptions === void 0 ? void 0 : treeOptions.enabled) === true &&
+                    column.dataField === firstVisibleDataField;
+                const expanded = isTreeColumn ? isRowExpanded(rowData) : false;
                 return (_jsxs(TD, { className: `mfui-td column-${column.columnId}`, "data-field": column.dataField, style: {
                         width: column.width,
                         minWidth: column.minWidth,
                         flex: column.width ? "0 0 auto" : "1",
-                    }, children: [(column === null || column === void 0 ? void 0 : column.enableResize) === true && _jsx(ColumnResizer, { column: column }), _jsx(InnerCellContent, { className: "mfui inner-cell-content", children: column.render
-                                ? column.render({
-                                    rowData,
-                                    onRowUpdated,
-                                })
-                                : rowData[column.dataField] })] }, index));
+                    }, children: [(column === null || column === void 0 ? void 0 : column.enableResize) === true && _jsx(ColumnResizer, { column: column }), _jsx(InnerCellContent, { className: "mfui inner-cell-content", children: isTreeColumn ? (_jsxs(TreeCellWrapper, { children: [_jsx(TreeIndentSpacer, { "$level": (_a = rowData.__level) !== null && _a !== void 0 ? _a : 0, "$indentPx": treeOptions.indentPx }), rowData.__hasChildren ? (_jsx(TreeChevronButton, { type: "button", "$expanded": expanded, onClick: (e) => {
+                                            e.stopPropagation();
+                                            toggleRowExpanded(rowData);
+                                        }, "aria-label": expanded ? "Collapse row" : "Expand row", "aria-expanded": expanded, children: _jsx(ChevronRightIcon, { size: 12 }) })) : (_jsx(TreeChevronPlaceholder, {})), _jsx(TreeCellContent, { children: cellBody })] })) : (cellBody) })] }, index));
             })] }));
 };
 export default TableRow;

package/dist/Table/types.d.ts

@@ -10,6 +10,42 @@ export type StateStorage = {
     type: "localStorage";
     key: string;
 };
+export type TreeMode = "nested" | "flat";
+export type TreeOptions = {
+    /** Enable tree-row behavior. Default: false */
+    enabled?: boolean;
+    /** Input shape. Default: "nested" */
+    mode?: TreeMode;
+    /** For mode="nested": field name that holds child array. Default: "children" */
+    childrenField?: string;
+    /** For mode="flat": field name that holds parent id. Default: "parentId" */
+    parentIdField?: string;
+    /** For mode="flat": field name that holds the row's stable id. Falls back to keyField. */
+    idField?: string;
+    /** Pixel width of one indentation level. Default: 16 */
+    indentPx?: number;
+    /** If a descendant matches search/filter, auto-expand its ancestors for the effective view. Default: true */
+    autoExpandOnMatch?: boolean;
+};
+export type ResolvedTreeOptions = {
+    enabled: boolean;
+    mode: TreeMode;
+    childrenField: string;
+    parentIdField: string;
+    idField?: string;
+    indentPx: number;
+    autoExpandOnMatch: boolean;
+};
+export type ExpandedKeysState = string[];
+export type OnExpandedChangeFn = (keys: string[]) => void;
+export type TreeMeta = {
+    /** Map of row key -> parent row key (undefined for roots) */
+    parentKeyMap: Map<string, string | undefined>;
+    /** Map of parent key -> ordered list of direct child keys */
+    childrenKeyMap: Map<string | undefined, string[]>;
+    /** All row keys that have children (eligible for expansion) */
+    expandableKeys: string[];
+};
 export type RenderOptions = {
     rowData: any;
     onRowUpdated?: (context: {
@@ -55,6 +91,7 @@ export type TableState = {
     sortState?: SortState;
     filterState?: Query;
     searchState?: string;
+    expandedKeys?: ExpandedKeysState;
 };
 export interface onResizeFinishedProps {
     column: ColumnState;
@@ -102,6 +139,17 @@ export type TableContextType = {
     data: any[];
     totalRecords?: number;
     keyField?: string;
+    treeOptions: ResolvedTreeOptions;
+    firstVisibleDataField?: string;
+    expandedKeys: string[];
+    effectiveExpandedKeys: Set<string>;
+    isRowExpanded: (row: any) => boolean;
+    toggleRowExpanded: (row: any) => void;
+    expandRow: (row: any) => void;
+    collapseRow: (row: any) => void;
+    expandAllRows: () => void;
+    collapseAllRows: () => void;
+    onExpandedChange?: OnExpandedChangeFn;
     tableHeight?: number;
     tableMaxHeight?: number;
     tableMinHeight?: number;
@@ -213,6 +261,11 @@ export interface TableProviderProps {
     defaultFilterState?: Query;
     filterState?: Query;
     onFilterChange?: (e: Query) => void;
+    treeOptions?: ResolvedTreeOptions;
+    defaultExpandedKeys?: ExpandedKeysState;
+    expandedKeys?: ExpandedKeysState;
+    onExpandedChange?: OnExpandedChangeFn;
+    treeMeta?: TreeMeta;
 }
 export interface TableRowProps {
     rowData: {
@@ -334,6 +387,10 @@ export interface TableProps {
     defaultFilterState?: Query;
     filterState?: Query;
     onFilterChange?: (e: Query) => void;
+    treeOptions?: TreeOptions;
+    defaultExpandedKeys?: ExpandedKeysState;
+    expandedKeys?: ExpandedKeysState;
+    onExpandedChange?: OnExpandedChangeFn;
 }
 export type TableInstance = {
     columnState: ColumnState[];
@@ -354,4 +411,11 @@ export type TableInstance = {
     clearSearch: () => void;
     clearSelections: () => void;
     getTableState: () => TableState;
+    expandRow: (row: any) => void;
+    collapseRow: (row: any) => void;
+    toggleRowExpanded: (row: any) => void;
+    isRowExpanded: (row: any) => boolean;
+    expandAllRows: () => void;
+    collapseAllRows: () => void;
+    getExpandedRowKeys: () => string[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monolith-forensics/monolith-ui",
-  "version": "1.5.1",
+  "version": "1.5.2-dev.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "author": "Matt Danner (Monolith Forensics LLC)",