@multiplatform.one/table 6.0.0

package/src/components/DataTableGrouping/index.tsx

@@ -0,0 +1,902 @@
+import {
+  ChartBarIcon,
+  CalculatorIcon,
+  CaretDownIcon,
+  CaretRightIcon,
+  CaretUpIcon,
+  HashIcon,
+  MinusIcon,
+  PlusIcon,
+  GearIcon,
+} from "@phosphor-icons/react";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useCallback, useMemo, useState } from "react";
+import { Button, Select } from "@multiplatform.one/forms";
+import { Popover, Separator, Text, View, XStack, YStack } from "tamagui";
+import { useDataTableState } from "../DataTable/DataTableStateContext";
+
+export type AggregationFunction = "count" | "sum" | "avg" | "min" | "max" | "custom";
+
+export interface AggregationConfig {
+  column: string;
+  function: AggregationFunction;
+  label?: string;
+  customFunction?: (values: any[]) => any;
+}
+
+export interface GroupingConfig {
+  columns: string[];
+  aggregations: AggregationConfig[];
+  showEmptyGroups?: boolean;
+  expandedByDefault?: boolean;
+  maxDepth?: number;
+}
+
+export interface GroupedData<T = any> {
+  key: string;
+  value: any;
+  count: number;
+  aggregations: Record<string, any>;
+  items: T[];
+  children?: GroupedData<T>[];
+  level: number;
+  path: any[];
+}
+
+export interface DataTableGroupingProps<T = any> {
+  data?: T[];
+  columns?: Array<{
+    accessorKey?: string;
+    header?: string | React.ReactNode;
+    id?: string;
+    type?: "string" | "number" | "date" | "boolean";
+  }>;
+  groupBy?: string[];
+  aggregations?: AggregationConfig[];
+  onGroupingChange?: (config: GroupingConfig) => void;
+  renderGroupHeader?: (group: GroupedData<T>, level: number) => React.ReactNode;
+  renderGroupFooter?: (group: GroupedData<T>, level: number) => React.ReactNode;
+  showAggregations?: boolean;
+  expandedGroups?: Set<string>;
+  onExpandedGroupsChange?: (expanded: Set<string>) => void;
+  maxDepth?: number;
+}
+
+export function DataTableGrouping<T = any>(props: DataTableGroupingProps<T>) {
+  // Try to consume from DataTableStateContext (compound component pattern)
+  const ctx = useDataTableState();
+
+  // Resolve values: explicit props override context values
+  const data = props.data ?? (ctx?.computed.filteredData as T[]) ?? [];
+  const columns =
+    props.columns ??
+    (ctx
+      ? ctx.table.getAllColumns().map((col) => ({
+          id: col.id,
+          accessorKey: col.id,
+          header: typeof col.columnDef.header === "string" ? col.columnDef.header : col.id,
+        }))
+      : []);
+
+  const {
+    groupBy = [],
+    aggregations = [],
+    renderGroupHeader,
+    renderGroupFooter,
+    showAggregations = true as boolean,
+    expandedGroups = new Set(),
+    onExpandedGroupsChange,
+    maxDepth = 5,
+  } = props;
+
+  // Group the data
+  const groupedData = useMemo(() => {
+    if (!groupBy.length) return null;
+    return groupData(data, groupBy, aggregations, maxDepth);
+  }, [data, groupBy, aggregations, maxDepth]);
+
+  // Handle group expansion
+  const toggleGroupExpansion = useCallback(
+    (groupKey: string) => {
+      const newExpanded = new Set(expandedGroups);
+      if (newExpanded.has(groupKey)) {
+        newExpanded.delete(groupKey);
+      } else {
+        newExpanded.add(groupKey);
+      }
+      onExpandedGroupsChange?.(newExpanded);
+    },
+    [expandedGroups, onExpandedGroupsChange],
+  );
+
+  if (!groupedData) return null;
+
+  return (
+    <GroupedDataRenderer
+      groupedData={groupedData}
+      columns={columns}
+      level={0}
+      aggregations={aggregations}
+      showAggregations={showAggregations}
+      expandedGroups={expandedGroups}
+      onToggleExpansion={toggleGroupExpansion}
+      renderGroupHeader={renderGroupHeader}
+      renderGroupFooter={renderGroupFooter}
+    />
+  );
+}
+
+interface GroupedDataRendererProps<T = any> {
+  groupedData: GroupedData<T>[];
+  columns: DataTableGroupingProps<T>["columns"];
+  level: number;
+  aggregations: AggregationConfig[];
+  showAggregations?: boolean;
+  expandedGroups: Set<string>;
+  onToggleExpansion: (groupKey: string) => void;
+  renderGroupHeader?: (group: GroupedData<T>, level: number) => React.ReactNode;
+  renderGroupFooter?: (group: GroupedData<T>, level: number) => React.ReactNode;
+}
+
+function GroupedDataRenderer<T = any>({
+  groupedData,
+  columns,
+  level,
+  aggregations,
+  showAggregations,
+  expandedGroups,
+  onToggleExpansion,
+  renderGroupHeader,
+  renderGroupFooter,
+}: GroupedDataRendererProps<T>) {
+  return (
+    <YStack>
+      {groupedData.map((group) => {
+        const groupKey = getGroupKey(group);
+        const isExpanded = expandedGroups.has(groupKey);
+        const hasChildren = group.children && group.children.length > 0;
+
+        return (
+          <YStack key={groupKey}>
+            {/* Group Header */}
+            <GroupHeader
+              group={group}
+              level={level}
+              isExpanded={isExpanded}
+              hasChildren={!!hasChildren}
+              aggregations={aggregations}
+              showAggregations={showAggregations ?? true}
+              onToggleExpansion={() => onToggleExpansion(groupKey)}
+              renderCustomHeader={renderGroupHeader}
+            />
+
+            {/* Group Content */}
+            {isExpanded && (
+              <YStack marginLeft={level * 20}>
+                {group.children && group.children.length > 0 ? (
+                  <GroupedDataRenderer
+                    groupedData={group.children}
+                    columns={columns}
+                    level={level + 1}
+                    aggregations={aggregations}
+                    showAggregations={showAggregations}
+                    expandedGroups={expandedGroups}
+                    onToggleExpansion={onToggleExpansion}
+                    renderGroupHeader={renderGroupHeader}
+                    renderGroupFooter={renderGroupFooter}
+                  />
+                ) : (
+                  <GroupItems items={group.items} columns={columns} />
+                )}
+              </YStack>
+            )}
+
+            {/* Group Footer */}
+            {renderGroupFooter && isExpanded && (
+              <GroupFooter group={group} level={level} renderCustomFooter={renderGroupFooter} />
+            )}
+          </YStack>
+        );
+      })}
+    </YStack>
+  );
+}
+
+interface GroupHeaderProps<T = any> {
+  group: GroupedData<T>;
+  level: number;
+  isExpanded: boolean;
+  hasChildren: boolean;
+  aggregations: AggregationConfig[];
+  showAggregations?: boolean;
+  onToggleExpansion: () => void;
+  renderCustomHeader?: (group: GroupedData<T>, level: number) => React.ReactNode;
+}
+
+function GroupHeader<T = any>({
+  group,
+  level,
+  isExpanded,
+  hasChildren,
+  aggregations,
+  showAggregations,
+  onToggleExpansion,
+  renderCustomHeader,
+}: GroupHeaderProps<T>) {
+  const { knobProps } = useResolvedKnobs();
+
+  if (renderCustomHeader) {
+    return <View>{renderCustomHeader(group, level)}</View>;
+  }
+
+  return (
+    <XStack
+      {...knobProps.borderRadius}
+      alignItems="center"
+      padding="$3"
+      {...{ backgroundColor: "$color2" }}
+      borderLeftWidth={4}
+      borderLeftColor="$color6"
+      cursor="pointer"
+      hoverStyle={{
+        backgroundColor:
+          level === 0 ? "$accentBackground" : { backgroundColor: "$color2" }.backgroundColor,
+      }}
+      onPress={onToggleExpansion}
+    >
+      {/* Expansion Toggle */}
+      <View width={20} alignItems="center">
+        {hasChildren && (isExpanded ? <CaretDownIcon size={16} /> : <CaretRightIcon size={16} />)}
+      </View>
+
+      {/* Group Info */}
+      <YStack flex={1}>
+        <XStack alignItems="center" gap="$2">
+          <Text fontSize="$4" fontWeight="600">
+            {group.value || "No Value"}
+          </Text>
+          <Text fontSize="$3" color="$color10">
+            ({group.count} item{group.count !== 1 ? "s" : ""})
+          </Text>
+        </XStack>
+
+        {/* Aggregations */}
+        {showAggregations && aggregations.length > 0 && (
+          <XStack gap="$4" marginTop="$2">
+            {aggregations.map((agg, index) => (
+              <XStack key={index} alignItems="center" gap="$1">
+                <Text fontSize="$3" color="$color10">
+                  {agg.label || `${agg.function}(${agg.column})`}:
+                </Text>
+                <Text fontSize="$3" fontWeight="500">
+                  {group.aggregations[agg.column]?.[agg.function] || 0}
+                </Text>
+              </XStack>
+            ))}
+          </XStack>
+        )}
+      </YStack>
+    </XStack>
+  );
+}
+
+interface GroupItemsProps<T = any> {
+  items: T[];
+  columns?: Array<{
+    accessorKey?: string;
+    header?: string | React.ReactNode;
+    id?: string;
+  }>;
+}
+
+function GroupItems<T = any>({ items, columns = [] }: GroupItemsProps<T>) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <YStack>
+      {items.map((item, index) => (
+        <XStack
+          {...knobProps.borderRadius}
+          key={index}
+          padding="$2"
+          paddingLeft="$4"
+          backgroundColor={index % 2 === 0 ? "$background" : "$color2"}
+          borderBottomWidth={1}
+          borderBottomColor="$borderColor"
+        >
+          {columns.length > 0 ? (
+            columns.map((column, colIndex) => {
+              const key = column.accessorKey || column.id || `col-${colIndex}`;
+              const value = (item as any)[key];
+              return (
+                <View key={key} flex={1}>
+                  <Text fontSize="$3">{String(value ?? "")}</Text>
+                </View>
+              );
+            })
+          ) : (
+            <Text fontSize="$3">{JSON.stringify(item, null, 2)}</Text>
+          )}
+        </XStack>
+      ))}
+    </YStack>
+  );
+}
+
+// Group Footer Component
+
+interface GroupFooterProps<T = any> {
+  group: GroupedData<T>;
+  level: number;
+  renderCustomFooter: (group: GroupedData<T>, level: number) => React.ReactNode;
+}
+
+function GroupFooter<T = any>({ group, level, renderCustomFooter }: GroupFooterProps<T>) {
+  return <View marginLeft={level * 20}>{renderCustomFooter(group, level)}</View>;
+}
+
+// Grouping Configuration Component
+
+export interface DataTableGroupingConfigProps<_T = any> {
+  columns?: Array<{
+    accessorKey?: string;
+    header?: string | React.ReactNode;
+    id?: string;
+    type?: "string" | "number" | "date" | "boolean";
+  }>;
+  currentConfig: GroupingConfig;
+  onConfigChange: (config: GroupingConfig) => void;
+  disabled?: boolean;
+}
+
+export function DataTableGroupingConfig<T = any>(props: DataTableGroupingConfigProps<T>) {
+  // Try to consume from DataTableStateContext (compound component pattern)
+  const ctx = useDataTableState();
+
+  // Resolve values: explicit props override context values
+  const columns =
+    props.columns ??
+    (ctx
+      ? ctx.table.getAllColumns().map((col) => ({
+          id: col.id,
+          accessorKey: col.id,
+          header: typeof col.columnDef.header === "string" ? col.columnDef.header : col.id,
+        }))
+      : []);
+
+  const { currentConfig, onConfigChange, disabled = false } = props;
+
+  const { knobProps } = useResolvedKnobs();
+  const sz = knobProps.sizeToken;
+  const popoverMinWidth = sz === "$3" ? 320 : sz === "$5" ? 480 : 400;
+  const popoverMaxWidth = sz === "$3" ? 400 : sz === "$5" ? 560 : 500;
+  const [isOpen, setIsOpen] = useState(false);
+
+  // Available columns for grouping
+  const availableColumns = columns.filter((col) => {
+    const key = col.accessorKey || col.id || "";
+    return key && !currentConfig.columns.includes(key);
+  });
+
+  // Available columns for aggregation
+  const aggregatableColumns = columns.filter((col) => {
+    const type = "type" in col && col.type != null ? col.type : "string";
+    return ["number", "date"].includes(type);
+  });
+
+  const handleAddGroupBy = (columnKey: string) => {
+    const newConfig = {
+      ...currentConfig,
+      columns: [...currentConfig.columns, columnKey],
+    };
+    onConfigChange(newConfig);
+  };
+
+  const handleRemoveGroupBy = (columnKey: string) => {
+    const newConfig = {
+      ...currentConfig,
+      columns: currentConfig.columns.filter((col) => col !== columnKey),
+    };
+    onConfigChange(newConfig);
+  };
+
+  const handleAddAggregation = (aggregation: AggregationConfig) => {
+    const newConfig = {
+      ...currentConfig,
+      aggregations: [...currentConfig.aggregations, aggregation],
+    };
+    onConfigChange(newConfig);
+  };
+
+  const handleRemoveAggregation = (index: number) => {
+    const newConfig = {
+      ...currentConfig,
+      aggregations: currentConfig.aggregations.filter((_, i) => i !== index),
+    };
+    onConfigChange(newConfig);
+  };
+
+  return (
+    <Popover open={isOpen} onOpenChange={setIsOpen}>
+      <Popover.Trigger asChild>
+        <Button
+          size={knobProps.sizeToken}
+          variant="outlined"
+          icon={<GearIcon size={16} />}
+          disabled={disabled}
+          aria-label="Grouping configuration"
+        >
+          <XStack alignItems="center" gap="$2">
+            <ChartBarIcon size={16} />
+            <Text>Group & Aggregate</Text>
+            {(currentConfig.columns.length > 0 || currentConfig.aggregations.length > 0) && (
+              <View
+                backgroundColor="$color6"
+                borderRadius={knobProps.borderRadius.borderRadius}
+                paddingHorizontal="$1"
+                paddingVertical={2}
+                minWidth={20}
+                alignItems="center"
+              >
+                <Text fontSize="$2" color="white" fontWeight="600">
+                  {currentConfig.columns.length + currentConfig.aggregations.length}
+                </Text>
+              </View>
+            )}
+          </XStack>
+        </Button>
+      </Popover.Trigger>
+
+      <Popover.Content
+        {...knobProps.borderRadius}
+        borderWidth={1}
+        borderColor="$borderColor"
+        enterStyle={{ x: 0, y: -10, opacity: 0 }}
+        exitStyle={{ x: 0, y: -10, opacity: 0 }}
+        minWidth={popoverMinWidth}
+        maxWidth={popoverMaxWidth}
+      >
+        <YStack {...knobProps.panelPadding} gap="$4">
+          <Text fontSize="$5" fontWeight="600">
+            Grouping & Aggregation
+          </Text>
+
+          {/* Group By Section */}
+          <YStack gap="$3">
+            <XStack justifyContent="space-between" alignItems="center">
+              <Text fontSize="$4" fontWeight="500">
+                Group By
+              </Text>
+              <Text fontSize="$2" color="$color10">
+                {currentConfig.columns.length} selected
+              </Text>
+            </XStack>
+
+            {/* Current Group By Columns */}
+            <YStack gap="$1">
+              {currentConfig.columns.map((columnKey, index) => {
+                const column = columns.find((col) => (col.accessorKey || col.id) === columnKey);
+                return (
+                  <XStack
+                    key={columnKey}
+                    alignItems="center"
+                    gap="$2"
+                    padding="$2"
+                    {...{ backgroundColor: "$color2" }}
+                    borderRadius={knobProps.borderRadius.borderRadius}
+                  >
+                    <Text fontSize="$3" flex={1}>
+                      {column?.header || columnKey} ({index + 1})
+                    </Text>
+                    <Button
+                      size={knobProps.sizeToken}
+                      variant="outlined"
+                      icon={<MinusIcon size={16} />}
+                      onPress={() => handleRemoveGroupBy(columnKey)}
+                      aria-label={`Remove grouping by ${column?.header || columnKey}`}
+                    />
+                  </XStack>
+                );
+              })}
+            </YStack>
+
+            {/* Add Group By Column */}
+            {availableColumns.length > 0 && (
+              <XStack gap="$2">
+                <Text fontSize="$3" color="$color10">
+                  Add:
+                </Text>
+                {availableColumns.slice(0, 3).map((column) => {
+                  const key = column.accessorKey || column.id || "";
+                  return (
+                    <Button
+                      key={key}
+                      size="$2"
+                      variant="outlined"
+                      onPress={() => handleAddGroupBy(key)}
+                    >
+                      {column.header || key}
+                    </Button>
+                  );
+                })}
+              </XStack>
+            )}
+          </YStack>
+
+          <Separator />
+
+          {/* Aggregation Section */}
+          <YStack gap="$3">
+            <XStack justifyContent="space-between" alignItems="center">
+              <Text fontSize="$4" fontWeight="500">
+                Aggregations
+              </Text>
+              <Text fontSize="$2" color="$color10">
+                {currentConfig.aggregations.length} configured
+              </Text>
+            </XStack>
+
+            {/* Current Aggregations */}
+            <YStack gap="$1">
+              {currentConfig.aggregations.map((agg, index) => (
+                <XStack
+                  key={index}
+                  alignItems="center"
+                  gap="$2"
+                  padding="$2"
+                  {...{ backgroundColor: "$color2" }}
+                  borderRadius={knobProps.borderRadius.borderRadius}
+                >
+                  <Text fontSize="$3" flex={1}>
+                    {agg.function}({agg.column}){agg.label && ` as "${agg.label}"`}
+                  </Text>
+                  <Button
+                    size={knobProps.sizeToken}
+                    variant="outlined"
+                    icon={<MinusIcon size={16} />}
+                    onPress={() => handleRemoveAggregation(index)}
+                    aria-label={`Remove ${agg.function} aggregation on ${agg.column}`}
+                  />
+                </XStack>
+              ))}
+            </YStack>
+
+            {/* Add Aggregation */}
+            <AggregationSelector
+              columns={aggregatableColumns}
+              onAddAggregation={handleAddAggregation}
+            />
+          </YStack>
+
+          {/* Clear All */}
+          {(currentConfig.columns.length > 0 || currentConfig.aggregations.length > 0) && (
+            <>
+              <Separator />
+              <Button
+                size={knobProps.sizeToken}
+                variant="outlined"
+                theme="red"
+                onPress={() => onConfigChange({ columns: [], aggregations: [] })}
+                aria-label="Clear all grouping and aggregation"
+              >
+                Clear All Grouping
+              </Button>
+            </>
+          )}
+        </YStack>
+      </Popover.Content>
+    </Popover>
+  );
+}
+
+// Aggregation Selector Component
+
+interface AggregationSelectorProps<_T = any> {
+  columns: Array<{
+    accessorKey?: string;
+    header?: string | React.ReactNode;
+    id?: string;
+    type?: "string" | "number" | "date" | "boolean";
+  }>;
+  onAddAggregation: (aggregation: AggregationConfig) => void;
+}
+
+function AggregationSelector<T = any>({ columns, onAddAggregation }: AggregationSelectorProps<T>) {
+  const [selectedColumn, setSelectedColumn] = useState<string>("");
+  const [selectedFunction, setSelectedFunction] = useState<AggregationFunction>("count");
+
+  const aggregationFunctions: Array<{
+    value: AggregationFunction;
+    label: string;
+    icon: React.ReactNode;
+  }> = [
+    { value: "count", label: "Count", icon: <HashIcon size={16} /> },
+    { value: "sum", label: "Sum", icon: <PlusIcon size={16} /> },
+    { value: "avg", label: "Average", icon: <CalculatorIcon size={16} /> },
+    { value: "min", label: "Minimum", icon: <MinusIcon size={16} /> },
+    { value: "max", label: "Maximum", icon: <CaretUpIcon size={16} /> },
+  ];
+
+  // Convert columns to forms Select options
+  const columnOptions = useMemo(
+    () =>
+      columns.map((column) => {
+        const key = column.accessorKey || column.id || "";
+        return {
+          value: key,
+          label: typeof column.header === "string" ? column.header : key,
+        };
+      }),
+    [columns],
+  );
+
+  // Convert aggregation functions to forms Select options
+  const functionOptions = useMemo(
+    () =>
+      aggregationFunctions.map((func) => ({
+        value: func.value,
+        label: func.label,
+      })),
+    [],
+  );
+
+  const handleAdd = () => {
+    if (!selectedColumn) return;
+
+    const column = columns.find((col) => (col.accessorKey || col.id) === selectedColumn);
+    const aggregation: AggregationConfig = {
+      column: selectedColumn,
+      function: selectedFunction,
+      label: `${selectedFunction} of ${column?.header || selectedColumn}`,
+    };
+
+    onAddAggregation(aggregation);
+    setSelectedColumn("");
+    setSelectedFunction("count");
+  };
+
+  return (
+    <YStack gap="$2">
+      <Text fontSize="$3" fontWeight="500">
+        Add Aggregation
+      </Text>
+
+      <XStack gap="$2" alignItems="flex-end">
+        <View flex={1}>
+          <Select
+            value={selectedColumn}
+            onValueChange={(v) => {
+              if (typeof v === "string") {
+                setSelectedColumn(v);
+              }
+            }}
+            options={columnOptions}
+            placeholder="Select column..."
+            compact
+            aria-label="Aggregation column"
+          />
+        </View>
+
+        <View width={140}>
+          <Select
+            value={selectedFunction}
+            onValueChange={(v) => {
+              if (typeof v === "string") {
+                setSelectedFunction(v as AggregationFunction);
+              }
+            }}
+            options={functionOptions}
+            compact
+            aria-label="Aggregation function"
+          />
+        </View>
+
+        <Button size="$2" variant="outlined" disabled={!selectedColumn} onPress={handleAdd}>
+          Add
+        </Button>
+      </XStack>
+    </YStack>
+  );
+}
+
+// Data Grouping Utilities
+
+export function groupData<T>(
+  data: T[],
+  groupByColumns: string[],
+  aggregations: AggregationConfig[],
+  maxDepth = 5,
+) {
+  if (!groupByColumns.length) return null;
+
+  const grouped = new Map<string, { items: T[]; key: any; path: any[] }>();
+
+  // Group data by the first column
+  data.forEach((item) => {
+    const firstGroupValue = (item as any)[groupByColumns[0]];
+    const key = String(firstGroupValue || "null");
+
+    if (!grouped.has(key)) {
+      grouped.set(key, {
+        items: [],
+        key: firstGroupValue,
+        path: [firstGroupValue],
+      });
+    }
+
+    const groupData = grouped.get(key);
+    if (groupData) {
+      groupData.items.push(item);
+    }
+  });
+
+  // Convert to GroupedData format
+  const result = Array.from(grouped.entries()).map(([key, group]) => {
+    const aggregationsResult: Record<string, any> = {};
+
+    // Calculate aggregations
+    aggregations.forEach((agg) => {
+      if (!aggregationsResult[agg.column]) {
+        aggregationsResult[agg.column] = {};
+      }
+
+      const values = group.items
+        .map((item) => (item as any)[agg.column])
+        .filter((val) => val != null);
+
+      switch (agg.function) {
+        case "count":
+          aggregationsResult[agg.column].count = group.items.length;
+          break;
+        case "sum": {
+          aggregationsResult[agg.column].sum = values.reduce(
+            (sum, val) => sum + (Number(val) || 0),
+            0,
+          );
+          break;
+        }
+        case "avg": {
+          const sum = values.reduce((sum, val) => sum + (Number(val) || 0), 0);
+          aggregationsResult[agg.column].avg =
+            values.length > 0 ? Math.round((sum / values.length) * 100) / 100 : 0;
+          break;
+        }
+        case "min": {
+          aggregationsResult[agg.column].min =
+            values.length > 0 ? Math.min(...values.map(Number)) : 0;
+          break;
+        }
+        case "max": {
+          aggregationsResult[agg.column].max =
+            values.length > 0 ? Math.max(...values.map(Number)) : 0;
+          break;
+        }
+        case "custom":
+          aggregationsResult[agg.column].custom = agg.customFunction
+            ? agg.customFunction(values)
+            : null;
+          break;
+      }
+    });
+
+    const groupedItem: GroupedData<T> = {
+      key,
+      value: group.key,
+      count: group.items.length,
+      aggregations: aggregationsResult,
+      items: group.items,
+      level: 0,
+      path: group.path,
+    };
+
+    // Recursively group children if more columns
+    if (groupByColumns.length > 1 && groupedItem.level < maxDepth - 1) {
+      const childGroups = groupData(group.items, groupByColumns.slice(1), aggregations, maxDepth);
+      if (childGroups) {
+        groupedItem.children = childGroups.map((child) => ({
+          ...child,
+          level: child.level + 1,
+          path: [group.key, ...child.path],
+        }));
+      }
+    }
+
+    return groupedItem;
+  });
+
+  return result;
+}
+
+function getGroupKey(group: GroupedData): string {
+  return group.path.join(" → ");
+}
+
+// Hook for Grouping
+
+export interface UseGroupingOptions<T = any> {
+  data: T[];
+  columns: Array<{
+    accessorKey?: string;
+    header?: string | React.ReactNode;
+    id?: string;
+    type?: "string" | "number" | "date" | "boolean";
+  }>;
+  initialConfig?: Partial<GroupingConfig>;
+}
+
+export interface UseGroupingReturn<T = any> {
+  groupedData: GroupedData<T>[] | null;
+  config: GroupingConfig;
+  setConfig: (config: GroupingConfig) => void;
+  expandedGroups: Set<string>;
+  setExpandedGroups: (groups: Set<string>) => void;
+  toggleGroupExpansion: (groupKey: string) => void;
+  expandAll: () => void;
+  collapseAll: () => void;
+  isGrouped: boolean;
+}
+
+export function useGrouping<T = any>({
+  data,
+  initialConfig = {},
+}: UseGroupingOptions<T>): UseGroupingReturn<T> {
+  const [config, setConfig] = useState<GroupingConfig>({
+    columns: [],
+    aggregations: [],
+    showEmptyGroups: false,
+    expandedByDefault: false,
+    maxDepth: 5,
+    ...initialConfig,
+  });
+
+  const [expandedGroups, setExpandedGroups] = useState<Set<string>>(new Set());
+
+  const groupedData = useMemo(() => {
+    if (!config.columns.length) return null;
+    return groupData(data, config.columns, config.aggregations, config.maxDepth);
+  }, [data, config]);
+
+  const toggleGroupExpansion = useCallback((groupKey: string) => {
+    setExpandedGroups((prev) => {
+      const newSet = new Set(prev);
+      if (newSet.has(groupKey)) {
+        newSet.delete(groupKey);
+      } else {
+        newSet.add(groupKey);
+      }
+      return newSet;
+    });
+  }, []);
+
+  const expandAll = useCallback(() => {
+    if (!groupedData) return;
+
+    const allKeys = new Set<string>();
+    const collectKeys = (groups: GroupedData<T>[]) => {
+      groups.forEach((group) => {
+        allKeys.add(getGroupKey(group));
+        if (group.children) {
+          collectKeys(group.children);
+        }
+      });
+    };
+
+    collectKeys(groupedData);
+    setExpandedGroups(allKeys);
+  }, [groupedData]);
+
+  const collapseAll = useCallback(() => {
+    setExpandedGroups(new Set());
+  }, []);
+
+  return {
+    groupedData,
+    config,
+    setConfig,
+    expandedGroups,
+    setExpandedGroups,
+    toggleGroupExpansion,
+    expandAll,
+    collapseAll,
+    isGrouped: config.columns.length > 0,
+  };
+}