@svgrid/grid 2.2.31 → 2.2.33

package/src/svgrid.tree-data.test.ts

@@ -0,0 +1,186 @@
+/**
+ * DOM: `treeData` renders a client-side hierarchy (#26).
+ *
+ * The point of the design is that tree rows stay REAL data rows: they render
+ * their own cells, so editing/formatting/selection all keep working, and only
+ * gain an expander plus indentation in the tree column. Grouping's banners are
+ * synthetic full-width rows - a tree row must never be rendered like one.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  createCoreRowModel,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  flattenTreeData,
+  sortFns,
+  tableFeatures,
+  rowSortingFeature,
+} from './index'
+
+type Node = { id: number; managerId: number | null; name: string; team: string }
+
+const data: Node[] = [
+  { id: 1, managerId: null, name: 'Ada', team: 'Exec' },
+  { id: 2, managerId: 1, name: 'Grace', team: 'Eng' },
+  { id: 3, managerId: 2, name: 'Alan', team: 'Eng' },
+  { id: 4, managerId: 1, name: 'Linus', team: 'Ops' },
+]
+
+const columns = [
+  { field: 'name', header: 'Name', width: 200 },
+  { field: 'team', header: 'Team', width: 120 },
+]
+
+const features = tableFeatures({ rowSortingFeature })
+const tick = () => new Promise<void>((r) => queueMicrotask(r))
+
+function mountGrid(extra: Record<string, unknown> = {}) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvGrid, {
+    target,
+    props: {
+      data,
+      columns,
+      features,
+      treeData: { parentField: 'managerId', column: 'name' },
+      _rowModels: {
+        coreRowModel: createCoreRowModel(),
+        filteredRowModel: createFilteredRowModel(),
+        sortedRowModel: createSortedRowModel(sortFns),
+        paginatedRowModel: createPaginatedRowModel(),
+      },
+      containerHeight: 600,
+      virtualization: false,
+      ...extra,
+    } as never,
+  })
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+
+let cleanup: (() => void) | null = null
+afterEach(() => { cleanup?.(); cleanup = null })
+
+const bodyRows = (t: HTMLElement) =>
+  [...t.querySelectorAll('tbody tr.sv-grid-row')].filter(
+    (r) => !r.classList.contains('sv-grid-row-spacer'),
+  )
+const toggles = (t: HTMLElement) =>
+  [...t.querySelectorAll<HTMLButtonElement>('.sv-grid-tree-toggle')]
+
+describe('treeData', () => {
+  it('shows only roots until expanded', async () => {
+    const { target, destroy } = mountGrid()
+    cleanup = destroy
+    await tick()
+    expect(bodyRows(target)).toHaveLength(1)
+    expect(target.textContent).toContain('Ada')
+    expect(target.textContent).not.toContain('Grace')
+  })
+
+  it('expands to reveal children', async () => {
+    const { target, destroy } = mountGrid()
+    cleanup = destroy
+    await tick()
+    toggles(target)[0]!.click()
+    await tick()
+    expect(target.textContent).toContain('Grace')
+    expect(target.textContent).toContain('Linus')
+    // Alan is a grandchild - still hidden.
+    expect(target.textContent).not.toContain('Alan')
+  })
+
+  it('renders tree rows as normal cell rows, not full-width banners', async () => {
+    const { target, destroy } = mountGrid()
+    cleanup = destroy
+    await tick()
+    expect(target.querySelectorAll('tr.sv-grid-group-row')).toHaveLength(0)
+    // The root has its own cells - both columns render.
+    const cells = bodyRows(target)[0]!.querySelectorAll('.sv-grid-cell')
+    expect(cells.length).toBeGreaterThanOrEqual(2)
+    expect(bodyRows(target)[0]!.textContent).toContain('Exec')
+  })
+
+  it('uses the treegrid role with aria-level and aria-expanded', async () => {
+    const { target, destroy } = mountGrid()
+    cleanup = destroy
+    await tick()
+    expect(target.querySelector('[role="treegrid"]')).not.toBeNull()
+    const root = bodyRows(target)[0]!
+    expect(root.getAttribute('aria-level')).toBe('1')
+    expect(root.getAttribute('aria-expanded')).toBe('false')
+
+    toggles(target)[0]!.click()
+    await tick()
+    expect(bodyRows(target)[0]!.getAttribute('aria-expanded')).toBe('true')
+    // A child sits one level deeper.
+    expect(bodyRows(target)[1]!.getAttribute('aria-level')).toBe('2')
+  })
+
+  it('indents from ONE source only', async () => {
+    // `sv-grid-group-child-indent` exists for rows nested under a group banner
+    // and keys off `row.depth`, which tree rows also have. It used to stack on
+    // top of the tree indent, putting a 20px gap between a row's chevron and
+    // its text - the tree affordance owns indentation here.
+    const { target, destroy } = mountGrid()
+    cleanup = destroy
+    await tick()
+    toggles(target)[0]!.click()
+    await tick()
+
+    expect(target.querySelectorAll('.sv-grid-group-child-indent')).toHaveLength(0)
+    // Every name cell still carries exactly one tree indent.
+    const nameCells = [...target.querySelectorAll('[data-col-id="name"]')]
+    for (const cell of nameCells) {
+      expect(cell.querySelectorAll('.sv-grid-tree-indent')).toHaveLength(1)
+    }
+  })
+
+  it('indents by depth x indentPx, honouring the override', async () => {
+    const { target, destroy } = mountGrid({
+      treeData: { parentField: 'managerId', column: 'name', indentPx: 30 },
+    })
+    cleanup = destroy
+    await tick()
+    toggles(target)[0]!.click()
+    await tick()
+    const widths = [...target.querySelectorAll<HTMLElement>('[data-col-id="name"] .sv-grid-tree-indent')]
+      .map((e) => e.style.width)
+    // Root at 0, its children one level in.
+    expect(widths[0]).toBe('0px')
+    expect(widths[1]).toBe('30px')
+  })
+
+  it('gives a leaf no expander but keeps it indented', async () => {
+    const { target, destroy } = mountGrid()
+    cleanup = destroy
+    await tick()
+    toggles(target)[0]!.click()
+    await tick()
+    // Linus is a leaf: spacer, no toggle button.
+    const linus = bodyRows(target).find((r) => r.textContent?.includes('Linus'))!
+    expect(linus.querySelector('.sv-grid-tree-toggle')).toBeNull()
+    expect(linus.querySelector('.sv-grid-tree-spacer')).not.toBeNull()
+    expect(linus.querySelector('.sv-grid-tree-indent')).not.toBeNull()
+  })
+
+  it('accepts nested data once flattened', async () => {
+    const nested = [
+      { id: 1, name: 'Ada', team: 'Exec', reports: [{ id: 2, name: 'Grace', team: 'Eng' }] },
+    ]
+    const flat = flattenTreeData(nested as never, { childrenField: 'reports' })
+    const { target, destroy } = mountGrid({
+      data: flat,
+      treeData: { parentField: '__parentId', column: 'name' },
+    })
+    cleanup = destroy
+    await tick()
+    expect(bodyRows(target)).toHaveLength(1)
+    toggles(target)[0]!.click()
+    await tick()
+    expect(target.textContent).toContain('Grace')
+  })
+})

package/src/svgriddropdown.async-panel.svelte.test.ts

@@ -0,0 +1,195 @@
+/**
+ * The dropdown panel's geometry is derived from the option COUNT, and it used
+ * to be measured only when the panel opened.
+ *
+ * With an async `editorOptions` the list is empty at that moment, so the panel
+ * was anchored and sized for ZERO options - about 8px tall. The options then
+ * arrived and rendered outside that box, unstyled, with the grid rows visible
+ * behind them. Reported from demo 428 as a broken editor.
+ *
+ * jsdom has no layout, so these assert the contract that produces the right
+ * geometry: the panel re-measures the trigger whenever the visible option list
+ * changes while it is open.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGridDropdown from './SvGridDropdown.svelte'
+
+const tick = () => new Promise<void>((r) => setTimeout(r, 0))
+const settle = async () => { for (let i = 0; i < 4; i += 1) await tick() }
+
+let cleanup: (() => void) | null = null
+afterEach(() => { cleanup?.(); cleanup = null })
+
+type Opt = { value: string; label: string }
+const opts = (...labels: string[]): Opt[] => labels.map((l) => ({ value: l, label: l }))
+
+/** Count trigger measurements, which is how the panel is anchored + sized. */
+function trackRectReads(rect?: Partial<DOMRect>) {
+  const reads: number[] = []
+  const orig = HTMLElement.prototype.getBoundingClientRect
+  HTMLElement.prototype.getBoundingClientRect = function () {
+    reads.push(1)
+    return {
+      top: 100, left: 0, width: 160, height: 30,
+      bottom: 130, right: 160, x: 0, y: 100, toJSON() {},
+      ...rect,
+    } as DOMRect
+  }
+  return { reads, restore: () => { HTMLElement.prototype.getBoundingClientRect = orig } }
+}
+
+const panelEl = () => document.querySelector('.sv-grid-dropdown-panel') as HTMLElement
+
+const optionEls = () => document.querySelectorAll('.sv-grid-dropdown-option')
+const emptyEl = () => document.querySelector('.sv-grid-dropdown-empty')
+
+describe('dropdown panel with a late-arriving option list', () => {
+  it('re-measures the trigger when options land after opening', async () => {
+    const t = trackRectReads()
+    try {
+      const target = document.createElement('div')
+      document.body.appendChild(target)
+      // Opens with an empty list, exactly like an async source.
+      const props = $state({ options: [] as Opt[], value: null, onChange: () => {} })
+      const app = mount(SvGridDropdown, { target, props: props as never })
+      cleanup = () => { unmount(app); target.remove() }
+      await settle()
+
+      expect(optionEls()).toHaveLength(0)
+      const afterOpen = t.reads.length
+      expect(afterOpen).toBeGreaterThan(0)
+
+      // The request resolves.
+      props.options = opts('Paris', 'Lyon', 'Marseille', 'Toulouse', 'Bordeaux')
+      await settle()
+
+      expect(optionEls()).toHaveLength(5)
+      // Sized for an empty list and never re-measured is the bug; the panel has
+      // to consult the trigger again once it has real content.
+      expect(t.reads.length).toBeGreaterThan(afterOpen)
+    } finally {
+      t.restore()
+    }
+  })
+
+  it('re-measures when a search filter shrinks the list', async () => {
+    const t = trackRectReads()
+    try {
+      const target = document.createElement('div')
+      document.body.appendChild(target)
+      const props = $state({
+        options: opts('Paris', 'Lyon', 'Marseille'),
+        value: null, searchable: true, onChange: () => {},
+      })
+      const app = mount(SvGridDropdown, { target, props: props as never })
+      cleanup = () => { unmount(app); target.remove() }
+      await settle()
+      const before = t.reads.length
+
+      const search = document.querySelector('.sv-grid-dropdown-search') as HTMLInputElement
+      search.value = 'lyo'
+      search.dispatchEvent(new Event('input', { bubbles: true }))
+      await settle()
+
+      expect(optionEls()).toHaveLength(1)
+      expect(t.reads.length).toBeGreaterThan(before)
+    } finally {
+      t.restore()
+    }
+  })
+
+  it('shows Loading rather than "No options" while a list is in flight', async () => {
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const app = mount(SvGridDropdown, {
+      target,
+      props: { options: [], value: null, loading: true, onChange: () => {} } as never,
+    })
+    cleanup = () => { unmount(app); target.remove() }
+    await settle()
+    expect(emptyEl()?.textContent).toContain('Loading')
+    // Announced, so a screen reader hears the list arrive.
+    expect(emptyEl()?.getAttribute('role')).toBe('status')
+  })
+
+  it('still says "No options" when the list is genuinely empty', async () => {
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const app = mount(SvGridDropdown, {
+      target,
+      props: { options: [], value: null, loading: false, onChange: () => {} } as never,
+    })
+    cleanup = () => { unmount(app); target.remove() }
+    await settle()
+    expect(emptyEl()?.textContent).toContain('No options')
+  })
+
+  it('is not capped by the row-height estimate when the list fits', async () => {
+    // `anchoredRect` clamps its `maxHeight` to our estimate, which assumes a
+    // 32px row. Themes with a bigger font render taller rows, so capping the
+    // panel at that estimate cut off the last option. A short list must be
+    // limited only by the real room available.
+    const t = trackRectReads({ top: 100, bottom: 130 })
+    try {
+      const target = document.createElement('div')
+      document.body.appendChild(target)
+      const app = mount(SvGridDropdown, {
+        target,
+        props: { options: opts('FR', 'JP', 'US'), value: null, onChange: () => {} } as never,
+      })
+      cleanup = () => { unmount(app); target.remove() }
+      await settle()
+
+      const max = parseFloat(panelEl().style.maxHeight)
+      // The 3-row estimate is 3*32 + 8 = 104. Anything at or under that would
+      // clip; the real space below the trigger is far larger.
+      expect(max).toBeGreaterThan(104)
+    } finally {
+      t.restore()
+    }
+  })
+
+  it('anchors an upward panel by its bottom edge', async () => {
+    // Upward panels used to be positioned by `top`, derived from the same
+    // estimate. Now that the panel may exceed the estimate, a top-anchored one
+    // would grow DOWN over the trigger; bottom-anchoring makes it grow up.
+    const t = trackRectReads({ top: 4000, bottom: 4030 })
+    try {
+      const target = document.createElement('div')
+      document.body.appendChild(target)
+      const app = mount(SvGridDropdown, {
+        target,
+        props: {
+          options: opts(...Array.from({ length: 12 }, (_, i) => `Opt ${i}`)),
+          value: null, onChange: () => {},
+        } as never,
+      })
+      cleanup = () => { unmount(app); target.remove() }
+      await settle()
+
+      const el = panelEl()
+      expect(el.style.bottom).not.toBe('')
+      expect(el.style.top).toBe('')
+    } finally {
+      t.restore()
+    }
+  })
+
+  it('swaps Loading for the options once they resolve', async () => {
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const props = $state({ options: [] as Opt[], value: null, loading: true, onChange: () => {} })
+    const app = mount(SvGridDropdown, { target, props: props as never })
+    cleanup = () => { unmount(app); target.remove() }
+    await settle()
+    expect(emptyEl()?.textContent).toContain('Loading')
+
+    props.options = opts('Paris', 'Lyon')
+    props.loading = false
+    await settle()
+
+    expect(emptyEl()).toBeNull()
+    expect(optionEls()).toHaveLength(2)
+  })
+})

package/src/themes/index.ts

@@ -35,6 +35,28 @@ export type ThemePalette = {
   pinnedBorder?: string
   /** Drop shadow cast by a pinned column into the scroll area. */
   pinnedShadow?: string
+  /* Semantic status colors. The UI kit reads these for destructive buttons,
+     validation errors, alert variants, badges and the rating star. A preset
+     that omits them gets the mode-appropriate defaults below, which match the
+     inline fallbacks the components shipped with - so adding these changed
+     nothing for existing presets, it only made them themeable. */
+  /** Errors, destructive actions, invalid cells. */
+  danger?: string
+  /** Confirmations, positive deltas. */
+  success?: string
+  /** Cautions, pending states, the rating star. */
+  warning?: string
+  /** Neutral informational callouts. */
+  info?: string
+  /** Focus outline color. Defaults to the preset's accent. */
+  focusRing?: string
+}
+
+/** Status-color defaults per mode - dark mode lifts them so they stay legible
+ *  on a dark ground. Values match the components' own inline fallbacks. */
+const STATUS_DEFAULTS: Record<ThemeMode, { danger: string; success: string; warning: string; info: string }> = {
+  light: { danger: '#dc2626', success: '#16a34a', warning: '#d97706', info: '#0891b2' },
+  dark: { danger: '#f87171', success: '#4ade80', warning: '#fbbf24', info: '#22d3ee' },
 }
 
 export type ThemePreset = {
@@ -156,6 +178,7 @@ export function resolveThemeTokens(preset: ThemePreset | undefined, mode: ThemeM
   const resolved = preset ?? defaultThemePreset
   const p = resolved[mode]
   const accent = accentOverride || p.accent
+  const status = STATUS_DEFAULTS[mode]
   return {
     '--sg-bg': p.bg,
     '--sg-fg': p.fg,
@@ -194,6 +217,25 @@ export function resolveThemeTokens(preset: ThemePreset | undefined, mode: ThemeM
     '--sg-on-accent': onAccent(accent),
     '--sg-radius': `${resolved.radius}px`,
     '--sg-font': resolved.font,
+    // Semantic status colors. Same reasoning as the scrollbar tokens below:
+    // the UI kit consumes these (destructive buttons, alerts, validation,
+    // badges, the rating star), so a preset that doesn't define them leaves
+    // every status color at a hard-coded red/green/amber that ignores the
+    // theme and, on dark presets, sits at the wrong lightness.
+    '--sg-danger': p.danger ?? status.danger,
+    '--sg-success': p.success ?? status.success,
+    '--sg-warning': p.warning ?? status.warning,
+    '--sg-info': p.info ?? status.info,
+    // A COLOR, not a shadow - consumed as `outline: 2px solid var(...)`.
+    '--sg-focus-ring': p.focusRing ?? accent,
+    // Derived surfaces + shape the kit reads. Deriving from the palette keeps
+    // them following the preset and the light/dark mode.
+    '--sg-muted-bg': p.rowHover,
+    '--sg-skeleton-bg': p.rowHover,
+    '--sg-radius-lg': `${resolved.radius * 2}px`,
+    '--sg-rating-on': p.warning ?? status.warning,
+    '--sg-rating-empty': p.border,
+    '--sg-invalid-fg': p.danger ?? status.danger,
     // The grid's custom scrollbar is a shadow-DOM web component that reads its
     // OWN --sg-scrollbar-* tokens (with fixed light-mode fallbacks). Without
     // these it ignores the theme entirely - a light scrollbar left on a dark

package/src/tree-edit.test.ts

@@ -20,7 +20,7 @@ describe('moveTreeNode', () => {
   it('moves inside a folder (appends to children)', () => {
     const out = moveTreeNode(tree, 'b', 'a', 'inside')
     expect(ids(out)).toEqual(['a', 'c'])
-    expect(out[0].children!.map((n) => n.id)).toEqual(['a1', 'a2', 'b'])
+    expect(out[0]!.children!.map((n) => n.id)).toEqual(['a1', 'a2', 'b'])
   })
   it('refuses to drop a node into its own descendant, or onto itself', () => {
     expect(moveTreeNode(tree, 'a', 'a1', 'inside')).toEqual(tree)
@@ -37,13 +37,13 @@ describe('sortTreeNodes', () => {
     ]
     const asc = sortTreeNodes(unsorted, (x, y) => x.label.localeCompare(y.label))
     expect(ids(asc)).toEqual(['a', 'm', 'z'])
-    expect(asc[1].children!.map((n) => n.label)).toEqual(['Apple', 'Pear'])
+    expect(asc[1]!.children!.map((n) => n.label)).toEqual(['Apple', 'Pear'])
   })
 })
 
 describe('treeContains', () => {
   it('detects descendants', () => {
-    expect(treeContains(tree[0], 'a2')).toBe(true)
-    expect(treeContains(tree[0], 'b')).toBe(false)
+    expect(treeContains(tree[0]!, 'a2')).toBe(true)
+    expect(treeContains(tree[0]!, 'b')).toBe(false)
   })
 })

package/src/tree-row-model.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from 'vitest'
+import { createTreeRowModel, flattenTreeData } from './core'
+
+type Node = { id: number; parent: number | null; name: string }
+
+/** Minimal Row stand-ins - the model only reads `original`, `id` and spreads. */
+function rowsFrom(data: Node[]) {
+  return data.map((original, index) => ({
+    id: String(original.id),
+    index,
+    original,
+    depth: 0,
+    getCanExpand: () => false,
+    getIsExpanded: () => false,
+    toggleExpanded: () => {},
+    getIsSelected: () => false,
+    toggleSelected: () => {},
+    getAllCells: () => [],
+    getCellValueByColumnId: (c: string) => (original as never as Record<string, unknown>)[c],
+  })) as never[]
+}
+
+let expandedState: Record<string, boolean> = {}
+const table = {
+  getState: () => ({ expanded: expandedState }),
+  setExpanded: (fn: (p: Record<string, boolean>) => Record<string, boolean>) => {
+    expandedState = fn(expandedState)
+  },
+} as never
+
+const run = (data: Node[], opts = { parentField: 'parent' }) =>
+  createTreeRowModel<never>(opts)({ table, rows: rowsFrom(data) } as never)
+
+const ids = (rows: readonly { id: string }[]) => rows.map((r) => r.id)
+
+describe('createTreeRowModel', () => {
+  const data: Node[] = [
+    { id: 1, parent: null, name: 'root' },
+    { id: 2, parent: 1, name: 'child a' },
+    { id: 3, parent: 1, name: 'child b' },
+    { id: 4, parent: 2, name: 'grandchild' },
+    { id: 5, parent: null, name: 'other root' },
+  ]
+
+  it('nests by parent id and returns only roots', () => {
+    const out = run(data)
+    expect(ids(out)).toEqual(['1', '5'])
+  })
+
+  it('records depth down the chain', () => {
+    const [root] = run(data) as never as Array<{ depth: number; subRows: never[] }>
+    expect(root!.depth).toBe(0)
+    const child = (root!.subRows as never as Array<{ id: string; depth: number; subRows: never[] }>)[0]!
+    expect(child.depth).toBe(1)
+    expect((child.subRows as never as Array<{ depth: number }>)[0]!.depth).toBe(2)
+  })
+
+  it('marks rows with children expandable and leaves not', () => {
+    const [root, other] = run(data) as never as Array<{ getCanExpand: () => boolean }>
+    expect(root!.getCanExpand()).toBe(true)
+    expect(other!.getCanExpand()).toBe(false)
+  })
+
+  it('counts descendants, not just direct children', () => {
+    const [root] = run(data) as never as Array<{ leafCount: number }>
+    // children a + b, plus a's grandchild
+    expect(root!.leafCount).toBe(3)
+  })
+
+  it('tags rows so they are not mistaken for group banners', async () => {
+    const { isGroupRow } = await import('./cell-values')
+    const [root] = run(data) as never as Array<never>
+    expect((root as never as { __treeRow: boolean }).__treeRow).toBe(true)
+    // Expandable, but must NOT render as a full-width banner.
+    expect(isGroupRow(root!)).toBe(false)
+  })
+
+  it('drives expansion through the table state', () => {
+    expandedState = {}
+    const [root] = run(data) as never as Array<{
+      getIsExpanded: () => boolean
+      toggleExpanded: () => void
+    }>
+    expect(root!.getIsExpanded()).toBe(false)
+    root!.toggleExpanded()
+    expect(expandedState['1']).toBe(true)
+  })
+
+  it('promotes a row whose parent is missing rather than dropping it', () => {
+    // Parent 99 does not exist - e.g. the filter removed it. The row must still
+    // be reachable.
+    const orphaned: Node[] = [
+      { id: 1, parent: null, name: 'root' },
+      { id: 2, parent: 99, name: 'orphan' },
+    ]
+    expect(ids(run(orphaned))).toEqual(['1', '2'])
+  })
+
+  it('survives a parent cycle', () => {
+    const cyclic: Node[] = [
+      { id: 1, parent: 2, name: 'a' },
+      { id: 2, parent: 1, name: 'b' },
+    ]
+    // Neither is a root by parent link, so nothing is emitted rather than
+    // recursing forever. The guard is what matters.
+    expect(() => run(cyclic)).not.toThrow()
+  })
+
+  it('treats a self-parenting row as a root', () => {
+    expect(ids(run([{ id: 1, parent: 1, name: 'self' }]))).toEqual(['1'])
+  })
+
+  it('passes an empty set straight through', () => {
+    expect(run([])).toEqual([])
+  })
+
+  it('honours a custom idField', () => {
+    const keyed = [
+      { key: 10, parent: null },
+      { key: 11, parent: 10 },
+    ] as never as Node[]
+    const out = createTreeRowModel<never>({ parentField: 'parent', idField: 'key' })({
+      table,
+      rows: rowsFrom(keyed),
+    } as never) as never as Array<{ subRows: never[] }>
+    expect(out).toHaveLength(1)
+    expect(out[0]!.subRows).toHaveLength(1)
+  })
+})
+
+describe('flattenTreeData', () => {
+  const nested = [
+    { id: 1, name: 'a', kids: [{ id: 2, name: 'a1', kids: [{ id: 3, name: 'a1a' }] }] },
+    { id: 4, name: 'b' },
+  ]
+
+  it('emits children directly after their parent', () => {
+    const flat = flattenTreeData(nested as never, { childrenField: 'kids' })
+    expect(flat.map((r) => (r as never as { id: number }).id)).toEqual([1, 2, 3, 4])
+  })
+
+  it('stamps the parent link the tree model reads', () => {
+    const flat = flattenTreeData(nested as never, { childrenField: 'kids' }) as never as Array<
+      Record<string, unknown>
+    >
+    expect(flat[0]!.__parentId).toBeNull()
+    expect(flat[1]!.__parentId).toBe(1)
+    expect(flat[2]!.__parentId).toBe(2)
+  })
+
+  it('round-trips into createTreeRowModel', () => {
+    const flat = flattenTreeData(nested as never, { childrenField: 'kids' })
+    const out = createTreeRowModel<never>({ parentField: '__parentId' })({
+      table,
+      rows: rowsFrom(flat as never as Node[]),
+    } as never) as never as Array<{ id: string; subRows: never[] }>
+    expect(out.map((r) => r.id)).toEqual(['1', '4'])
+    expect(out[0]!.subRows).toHaveLength(1)
+  })
+
+  it('accepts a custom parent field name', () => {
+    const flat = flattenTreeData(nested as never, {
+      childrenField: 'kids',
+      parentField: 'pid',
+    }) as never as Array<Record<string, unknown>>
+    expect(flat[1]!.pid).toBe(1)
+  })
+})