@shadng/sng-ui 1.0.0

package/src/lib/sng-table-core/core/create-column.ts

@@ -0,0 +1,266 @@
+/**
+ * @fileoverview Column creation and management for sng-table-core
+ */
+
+import {
+  Column,
+  ColumnDef,
+  Table,
+  AccessorFn,
+  ColumnPinningPosition,
+} from './types';
+import { flattenBy, getValueAtPath } from './utils';
+
+// ============================================================================
+// COLUMN CREATION
+// ============================================================================
+
+/**
+ * Create a column instance from a column definition
+ */
+export function createColumn<TData, TValue = unknown>(
+  table: Table<TData>,
+  columnDef: ColumnDef<TData, TValue>,
+  depth: number,
+  parent?: Column<TData, unknown>,
+  path: number[] = []
+): Column<TData, TValue> {
+  // Resolve column ID
+  const id = resolveColumnId(columnDef, path);
+
+  // Merge with default column options
+  const resolvedDef = {
+    ...table.options.defaultColumn,
+    ...columnDef,
+  } as ColumnDef<TData, TValue>;
+
+  // Create the column instance
+  const column: Column<TData, TValue> = {
+    id,
+    columnDef: resolvedDef,
+    depth,
+    parent,
+    columns: [], // Will be populated for group columns
+
+    getLeafColumns: () => getLeafColumns(column as Column<TData, unknown>),
+    getFlatColumns: () => getFlatColumns(column as Column<TData, unknown>),
+    getAccessorFn: () => getAccessorFn(column),
+    getIndex: (position?: ColumnPinningPosition) =>
+      getColumnIndex(table, column as Column<TData, unknown>, position),
+  };
+
+  // Recursively create child columns if this is a group column
+  if (resolvedDef.columns?.length) {
+    column.columns = resolvedDef.columns.map((childDef, childIndex) =>
+      createColumn(table, childDef, depth + 1, column as Column<TData, unknown>, [...path, childIndex])
+    );
+  }
+
+  return column;
+}
+
+/**
+ * Resolve column ID from column definition
+ */
+function resolveColumnId<TData, TValue>(
+  columnDef: ColumnDef<TData, TValue>,
+  path: number[]
+): string {
+  // Explicit ID takes precedence
+  if (columnDef.id) {
+    return columnDef.id;
+  }
+
+  // Use accessor key as ID
+  if (columnDef.accessorKey) {
+    return columnDef.accessorKey;
+  }
+
+  // Use accessor function name if available
+  if (columnDef.accessorFn) {
+    if (columnDef.accessorFn.name) {
+      return columnDef.accessorFn.name;
+    }
+  }
+
+  // No ID can be determined - this is an error for non-group columns
+  if (!columnDef.columns?.length) {
+    console.warn(
+      '[sng-table] Column definition requires either id, accessorKey, or accessorFn with a name:',
+      columnDef
+    );
+    return `column_${path.join('_') || '0'}`;
+  }
+
+  // Group columns without explicit ID get a deterministic one.
+  return `group_${path.join('_') || '0'}`;
+}
+
+/**
+ * Get accessor function for a column
+ */
+function getAccessorFn<TData, TValue>(
+  column: Column<TData, TValue>
+): AccessorFn<TData, TValue> | undefined {
+  const { accessorFn, accessorKey } = column.columnDef;
+
+  // Direct accessor function
+  if (accessorFn) {
+    return accessorFn;
+  }
+
+  // Create accessor from key
+  if (accessorKey) {
+    // Handle nested keys (e.g., 'user.profile.name')
+    if (accessorKey.includes('.')) {
+      return (row: TData) =>
+        getValueAtPath(row as Record<string, unknown>, accessorKey) as TValue;
+    }
+
+    // Simple key access
+    return (row: TData) => (row as Record<string, unknown>)[accessorKey] as TValue;
+  }
+
+  // No accessor - this is a display/group column
+  return undefined;
+}
+
+// ============================================================================
+// COLUMN TRAVERSAL
+// ============================================================================
+
+/**
+ * Get all leaf columns (columns without children) from this column's subtree
+ */
+function getLeafColumns<TData>(
+  column: Column<TData, unknown>
+): Column<TData, unknown>[] {
+  if (!column.columns.length) {
+    return [column];
+  }
+
+  return column.columns.flatMap((child) => getLeafColumns(child));
+}
+
+/**
+ * Get all columns (including groups) flattened from this column's subtree
+ */
+function getFlatColumns<TData>(
+  column: Column<TData, unknown>
+): Column<TData, unknown>[] {
+  return [column, ...column.columns.flatMap((child) => getFlatColumns(child))];
+}
+
+/**
+ * Get column index among siblings (considering pinning position if specified)
+ */
+function getColumnIndex<TData>(
+  table: Table<TData>,
+  column: Column<TData, unknown>,
+  position?: ColumnPinningPosition
+): number {
+  // Get the appropriate column list based on position
+  let columns: Column<TData, unknown>[];
+
+  if (position === 'left') {
+    columns = table.getLeftVisibleLeafColumns?.() ?? [];
+  } else if (position === 'right') {
+    columns = table.getRightVisibleLeafColumns?.() ?? [];
+  } else if (position === false) {
+    columns = table.getCenterVisibleLeafColumns?.() ?? [];
+  } else {
+    // Default: use all visible leaf columns
+    columns = table.getVisibleLeafColumns?.() ?? table.getAllLeafColumns();
+  }
+
+  return columns.findIndex((c) => c.id === column.id);
+}
+
+// ============================================================================
+// TABLE COLUMN HELPERS
+// ============================================================================
+
+/**
+ * Build all columns from column definitions
+ */
+export function buildColumns<TData>(
+  table: Table<TData>,
+  columnDefs: ColumnDef<TData, unknown>[]
+): Column<TData, unknown>[] {
+  return columnDefs.map((columnDef, columnIndex) =>
+    createColumn(table, columnDef, 0, undefined, [columnIndex])
+  );
+}
+
+/**
+ * Get all columns from column tree
+ */
+export function getAllColumns<TData>(
+  columns: Column<TData, unknown>[]
+): Column<TData, unknown>[] {
+  return columns;
+}
+
+/**
+ * Get all columns flattened (including nested)
+ */
+export function getAllFlatColumns<TData>(
+  columns: Column<TData, unknown>[]
+): Column<TData, unknown>[] {
+  return flattenBy(columns, (col) =>
+    col.columns.length ? col.columns : undefined
+  );
+}
+
+/**
+ * Get all leaf columns (no children)
+ */
+export function getAllLeafColumns<TData>(
+  columns: Column<TData, unknown>[]
+): Column<TData, unknown>[] {
+  return getAllFlatColumns(columns).filter((col) => !col.columns.length);
+}
+
+/**
+ * Get column by ID from flat columns
+ */
+export function getColumnById<TData>(
+  flatColumns: Column<TData, unknown>[],
+  columnId: string
+): Column<TData, unknown> | undefined {
+  return flatColumns.find((col) => col.id === columnId);
+}
+
+/**
+ * Order columns by column order state
+ */
+export function orderColumns<TData>(
+  columns: Column<TData, unknown>[],
+  columnOrder: string[]
+): Column<TData, unknown>[] {
+  if (!columnOrder.length) {
+    return columns;
+  }
+
+  // Create a map for fast lookup
+  const columnMap = new Map(columns.map((col) => [col.id, col]));
+
+  // Build ordered array
+  const ordered: Column<TData, unknown>[] = [];
+
+  // First, add columns in specified order
+  for (const id of columnOrder) {
+    const col = columnMap.get(id);
+    if (col) {
+      ordered.push(col);
+      columnMap.delete(id);
+    }
+  }
+
+  // Then, add any remaining columns not in order
+  for (const col of columnMap.values()) {
+    ordered.push(col);
+  }
+
+  return ordered;
+}

package/src/lib/sng-table-core/core/create-header.ts

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview Header creation and management for sng-table-core
+ */
+
+import {
+  Header,
+  HeaderContext,
+  HeaderGroup,
+  Column,
+  Table,
+  ColumnPinningPosition,
+} from './types';
+
+// ============================================================================
+// HEADER CREATION
+// ============================================================================
+
+/**
+ * Create a header instance for a column
+ */
+export function createHeader<TData, TValue = unknown>(
+  table: Table<TData>,
+  column: Column<TData, TValue>,
+  options: {
+    id?: string;
+    isPlaceholder?: boolean;
+    depth: number;
+    index: number;
+  }
+): Header<TData, TValue> {
+  const id = options.id ?? `${column.id}_${options.depth}`;
+
+  // Create the header instance
+  const header: Header<TData, TValue> = {
+    id,
+    column,
+    depth: options.depth,
+    index: options.index,
+    isPlaceholder: options.isPlaceholder ?? false,
+    colSpan: 1, // Will be calculated
+    rowSpan: 1, // Will be calculated
+    subHeaders: [], // Will be populated for group columns
+
+    getContext: () => getHeaderContext(table, column, header),
+
+    getLeafHeaders: () => getLeafHeaders(header),
+  };
+
+  return header;
+}
+
+// ============================================================================
+// HEADER CONTEXT
+// ============================================================================
+
+/**
+ * Create the header context for rendering
+ */
+function getHeaderContext<TData, TValue>(
+  table: Table<TData>,
+  column: Column<TData, TValue>,
+  header: Header<TData, TValue>
+): HeaderContext<TData, TValue> {
+  return {
+    table,
+    column,
+    header,
+  };
+}
+
+// ============================================================================
+// HEADER TRAVERSAL
+// ============================================================================
+
+/**
+ * Get all leaf headers from a header's subtree
+ */
+function getLeafHeaders<TData>(
+  header: Header<TData, unknown>
+): Header<TData, unknown>[] {
+  if (!header.subHeaders.length) {
+    return [header];
+  }
+
+  return header.subHeaders.flatMap((subHeader) => getLeafHeaders(subHeader));
+}
+
+// ============================================================================
+// HEADER GROUPS
+// ============================================================================
+
+/**
+ * Build header groups from columns
+ *
+ * Header groups represent rows of headers in the table head.
+ * For nested columns, this creates multiple rows with appropriate colSpan/rowSpan.
+ */
+export function buildHeaderGroups<TData>(
+  table: Table<TData>,
+  columns: Column<TData, unknown>[],
+  _position?: ColumnPinningPosition
+): HeaderGroup<TData>[] {
+  // Find the maximum depth of nested columns
+  const maxDepth = getMaxColumnDepth(columns);
+
+  // Build header groups from bottom to top
+  const headerGroups: HeaderGroup<TData>[] = [];
+
+  // Build each depth level
+  for (let depth = 0; depth <= maxDepth; depth++) {
+    const headers: Header<TData, unknown>[] = [];
+
+    // Get columns that should appear at this depth
+    const columnsAtDepth = getColumnsForDepth(columns, depth, maxDepth);
+
+    columnsAtDepth.forEach((col, index) => {
+      const isLeaf = !col.columns.length;
+      const actualDepth = col.depth;
+
+      // Create header for this column
+      const header = createHeader(table, col, {
+        depth,
+        index,
+        isPlaceholder: depth < actualDepth, // Placeholder if we're above the column's actual depth
+      });
+
+      // Calculate spans
+      if (isLeaf) {
+        // Leaf columns span all remaining rows
+        header.rowSpan = maxDepth - actualDepth + 1;
+        header.colSpan = 1;
+      } else {
+        // Group columns span their children
+        header.rowSpan = 1;
+        header.colSpan = col.getLeafColumns().length;
+      }
+
+      // Build sub-headers for group columns
+      if (col.columns.length) {
+        header.subHeaders = col.columns.map((childCol, childIndex) =>
+          createHeader(table, childCol, {
+            depth: depth + 1,
+            index: childIndex,
+            isPlaceholder: false,
+          })
+        );
+      }
+
+      headers.push(header);
+    });
+
+    headerGroups.push({
+      id: `header_group_${depth}`,
+      depth,
+      headers,
+    });
+  }
+
+  return headerGroups;
+}
+
+/**
+ * Get the maximum depth of nested columns
+ */
+function getMaxColumnDepth<TData>(columns: Column<TData, unknown>[]): number {
+  let maxDepth = 0;
+
+  function traverse(cols: Column<TData, unknown>[], currentDepth: number) {
+    for (const col of cols) {
+      maxDepth = Math.max(maxDepth, currentDepth);
+      if (col.columns.length) {
+        traverse(col.columns, currentDepth + 1);
+      }
+    }
+  }
+
+  traverse(columns, 0);
+  return maxDepth;
+}
+
+/**
+ * Group columns by their depth
+ * @internal Reserved for future use
+ */
+function _groupColumnsByDepth<TData>(
+  columns: Column<TData, unknown>[]
+): Map<number, Column<TData, unknown>[]> {
+  const result = new Map<number, Column<TData, unknown>[]>();
+
+  function traverse(cols: Column<TData, unknown>[]) {
+    for (const col of cols) {
+      const depth = col.depth;
+      if (!result.has(depth)) {
+        result.set(depth, []);
+      }
+      result.get(depth)!.push(col);
+
+      if (col.columns.length) {
+        traverse(col.columns);
+      }
+    }
+  }
+
+  traverse(columns);
+  return result;
+}
+
+/**
+ * Get columns that should appear at a specific depth level
+ * Includes placeholders for columns that appear at deeper levels
+ */
+function getColumnsForDepth<TData>(
+  columns: Column<TData, unknown>[],
+  targetDepth: number,
+  _maxDepth: number
+): Column<TData, unknown>[] {
+  const result: Column<TData, unknown>[] = [];
+
+  function traverse(cols: Column<TData, unknown>[], currentDepth: number) {
+    for (const col of cols) {
+      if (currentDepth === targetDepth) {
+        // This column should appear at this depth
+        result.push(col);
+      } else if (currentDepth < targetDepth && col.columns.length) {
+        // Recurse into children
+        traverse(col.columns, currentDepth + 1);
+      } else if (currentDepth < targetDepth && !col.columns.length) {
+        // Leaf column that starts earlier - need placeholder at this depth
+        // But we only show it once at its actual depth with rowSpan
+        // So skip here
+      }
+    }
+  }
+
+  traverse(columns, 0);
+  return result;
+}
+
+/**
+ * Build flattened header list from header groups
+ */
+export function getFlatHeaders<TData>(
+  headerGroups: HeaderGroup<TData>[]
+): Header<TData, unknown>[] {
+  return headerGroups.flatMap((group) => group.headers);
+}
+
+/**
+ * Get leaf headers (headers without sub-headers)
+ */
+export function getLeafHeadersFromGroups<TData>(
+  headerGroups: HeaderGroup<TData>[]
+): Header<TData, unknown>[] {
+  const lastGroup = headerGroups[headerGroups.length - 1];
+  return lastGroup?.headers ?? [];
+}
+
+/**
+ * Build footer groups (same structure as header groups, just from bottom of table)
+ */
+export function buildFooterGroups<TData>(
+  table: Table<TData>,
+  columns: Column<TData, unknown>[]
+): HeaderGroup<TData>[] {
+  // Footers are built the same way as headers
+  // The difference is in how they're rendered (at bottom of table)
+  return buildHeaderGroups(table, columns).map((group) => ({
+    ...group,
+    id: `footer_group_${group.depth}`,
+  }));
+}