feat(createDataGrid): add row spanning computation

Author: johnleider

packages/0/src/composables/createDataGrid/spanning.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+
+// Utilities
+import { computed } from 'vue'
+
+import { createRowSpanning } from './spanning'
+
+describe('createRowSpanning', () => {
+  it('returns empty map when no rowSpanning function', () => {
+    const spans = createRowSpanning({
+      items: computed(() => []),
+      columns: ['a', 'b'],
+    })
+    expect(spans.value.size).toBe(0)
+  })
+
+  it('computes span map for visible items', () => {
+    const items = computed(() => [
+      { id: 1, category: 'A', name: 'X' },
+      { id: 2, category: 'A', name: 'Y' },
+      { id: 3, category: 'B', name: 'Z' },
+    ])
+
+    const spans = createRowSpanning({
+      items,
+      columns: ['category', 'name'],
+      itemKey: 'id',
+      rowSpanning: (item, column) => {
+        if (column === 'category' && item.category === 'A') return 2
+        return 1
+      },
+    })
+
+    expect(spans.value.get(1)?.get('category')).toEqual({ rowSpan: 2, hidden: false })
+    expect(spans.value.get(2)?.get('category')).toEqual({ rowSpan: 1, hidden: true })
+    expect(spans.value.get(3)?.get('category')).toEqual({ rowSpan: 1, hidden: false })
+    expect(spans.value.get(1)?.get('name')).toEqual({ rowSpan: 1, hidden: false })
+  })
+
+  it('does not span beyond visible items', () => {
+    const items = computed(() => [
+      { id: 1, category: 'A' },
+      { id: 2, category: 'A' },
+    ])
+
+    const spans = createRowSpanning({
+      items,
+      columns: ['category'],
+      itemKey: 'id',
+      rowSpanning: (item, column) => {
+        if (column === 'category' && item.category === 'A') return 5
+        return 1
+      },
+    })
+
+    expect(spans.value.get(1)?.get('category')?.rowSpan).toBe(2)
+  })
+})

packages/0/src/composables/createDataGrid/spanning.ts

@@ -0,0 +1,71 @@
+/**
+ * @module createDataGrid/spanning
+ *
+ * @remarks
+ * Computes a row span map from visible items. For each cell, determines
+ * rowSpan and whether it's hidden (covered by a span from a previous row).
+ * Spans do not cross page boundaries.
+ */
+
+// Utilities
+import { computed } from 'vue'
+
+// Types
+import type { ID } from '#v0/types'
+import type { ComputedRef, Ref } from 'vue'
+
+export interface SpanEntry {
+  rowSpan: number
+  hidden: boolean
+}
+
+export interface RowSpanningOptions<T = Record<string, unknown>> {
+  items: Ref<readonly T[]> | ComputedRef<readonly T[]>
+  columns: readonly string[]
+  itemKey?: string
+  rowSpanning?: (item: T, column: string) => number
+}
+
+export function createRowSpanning<T extends Record<string, unknown>> (
+  options: RowSpanningOptions<T>,
+): ComputedRef<Map<ID, Map<string, SpanEntry>>> {
+  const { items, columns, itemKey = 'id', rowSpanning } = options
+
+  return computed(() => {
+    const result = new Map<ID, Map<string, SpanEntry>>()
+
+    if (!rowSpanning) return result
+
+    const list = items.value
+
+    // Track which cells are covered by a span from a previous row
+    // covered[colIndex] = number of remaining rows to skip
+    const covered = Array.from({ length: columns.length }).fill(0)
+
+    for (let row = 0; row < list.length; row++) {
+      const item = list[row]
+      const id = item[itemKey] as ID
+      const cellMap = new Map<string, SpanEntry>()
+
+      for (const [col, column] of columns.entries()) {
+        if (covered[col] > 0) {
+          cellMap.set(column, { rowSpan: 1, hidden: true })
+          covered[col]--
+        } else {
+          const span = Math.min(
+            Math.max(1, rowSpanning(item, column)),
+            list.length - row, // clamp to remaining rows
+          )
+          cellMap.set(column, { rowSpan: span, hidden: false })
+          if (span > 1) {
+            covered[col] = span - 1
+          }
+        }
+      }
+
+      result.set(id, cellMap)
+    }
+
+    return result
+  })
+}