@svgrid/grid 2.2.16 → 2.2.17

package/src/createMenu.svelte.ts

@@ -31,6 +31,7 @@
 import type { MenuItem } from './menu-item'
 import type { EditorDir } from './editor-contract'
 import { enabledIndices, wrapMove } from './list-nav'
+import { createTypeaheadBuffer, isTypeaheadKey } from './list-option'
 
 /** Reactive inputs are getters so the core tracks live prop changes (the same
  *  controlled pattern as `createListbox`). */
@@ -76,6 +77,22 @@ export function createMenu(config: MenuConfig) {
   let active = $state(-1)
   let openSub = $state(-1)
 
+  // Type-ahead: printable keys jump to the next item whose label starts with the
+  // accumulated buffer (WAI-ARIA menu behavior), wrapping past the active item.
+  const typeahead = createTypeaheadBuffer()
+  function typeaheadMatch(buffer: string): number {
+    const b = buffer.trim().toLowerCase()
+    if (!b) return -1
+    const its = items()
+    const n = its.length
+    for (let k = 1; k <= n; k++) {
+      const i = (active + k + n) % n
+      const it = its[i]
+      if (it && !it.disabled && !it.separator && (it.label ?? '').toLowerCase().startsWith(b)) return i
+    }
+    return -1
+  }
+
   // Real (non-separator, non-disabled) item indices, for roving focus.
   const focusables = $derived(
     enabledIndices(items().length, (i) => {
@@ -153,6 +170,12 @@ export function createMenu(config: MenuConfig) {
       // Tab leaves the menu entirely (WAI-ARIA menu-button pattern): close the
       // whole tree rather than trapping focus inside a portalled panel.
       case 'Tab': config.onClose(); break
+      default:
+        // Type-ahead: a bare printable key jumps to the matching item.
+        if (isTypeaheadKey(e)) {
+          const idx = typeaheadMatch(typeahead.push(e.key))
+          if (idx >= 0) { e.preventDefault(); focus(idx) }
+        }
     }
   }
 

package/src/createPopoverSelect.svelte.ts

@@ -23,6 +23,8 @@ export type PopoverSelectConfig = {
   itemCount: () => number
   /** Whether item `i` is disabled (skipped by roving, not selectable). */
   disabled?: (index: number) => boolean
+  /** Read-only: value shown, trigger focusable, but the panel will not open. */
+  readonly?: () => boolean
   /** Commit the item at `index` (Enter or a click the component forwards). */
   onSelect: (index: number) => void
   /** Notified whenever the open state changes. */
@@ -59,6 +61,7 @@ export function createPopoverSelect(config: PopoverSelectConfig) {
 
   const count = () => config.itemCount()
   const isDisabled = (i: number) => config.disabled?.(i) ?? false
+  const readonly = () => config.readonly?.() ?? false
 
   function enabledIndices(): number[] {
     return enabledIndicesOf(count(), isDisabled)
@@ -74,6 +77,7 @@ export function createPopoverSelect(config: PopoverSelectConfig) {
     config.onOpenChange?.(v)
   }
   function openPanel() {
+    if (readonly()) return
     active = clampActive(config.initialActive?.() ?? 0)
     setOpen(true)
   }
@@ -82,6 +86,7 @@ export function createPopoverSelect(config: PopoverSelectConfig) {
     config.getTrigger()?.focus()
   }
   function toggle() {
+    if (readonly()) return
     open ? setOpen(false) : openPanel()
   }
 
@@ -92,7 +97,7 @@ export function createPopoverSelect(config: PopoverSelectConfig) {
   function first() { active = enabledIndices()[0] ?? 0 }
   function last() { active = enabledIndices().at(-1) ?? 0 }
   function selectActive() {
-    if (count() === 0 || isDisabled(active)) return
+    if (readonly() || count() === 0 || isDisabled(active)) return
     config.onSelect(active)
     if (config.closeOnSelect?.() ?? true) closePanel()
   }
@@ -129,6 +134,7 @@ export function createPopoverSelect(config: PopoverSelectConfig) {
   })
 
   function onTriggerKeydown(e: KeyboardEvent) {
+    if (readonly()) return
     if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
       e.preventDefault()
       openPanel()
@@ -185,6 +191,7 @@ export function createPopoverSelect(config: PopoverSelectConfig) {
       'aria-haspopup': haspopup,
       'aria-expanded': open,
       'aria-controls': open ? panelId : undefined,
+      'aria-readonly': readonly() || undefined,
       onkeydown: onTriggerKeydown,
     }),
     /** Attributes for the element that OWNS focus + activedescendant (the panel,

package/src/createSlider.svelte.ts

@@ -19,6 +19,8 @@
  * </div>
  * ```
  */
+import { editorAria } from './editor-contract'
+
 export type SliderValue = number | [number, number]
 export type SliderOrientation = 'horizontal' | 'vertical'
 export type SliderThumb = 'single' | 'lo' | 'hi'
@@ -37,6 +39,12 @@ export type SliderConfig = {
   ariaLabel?: () => string | undefined
   /** Right-to-left: mirrors horizontal pointer + Left/Right key direction. */
   rtl?: () => boolean
+  // Editor contract (validation ARIA) - folded into thumbProps.
+  id?: () => string | undefined
+  invalid?: () => boolean | undefined
+  required?: () => boolean | undefined
+  error?: () => string | undefined
+  hint?: () => string | undefined
 }
 
 export function createSlider(config: SliderConfig) {
@@ -153,6 +161,15 @@ export function createSlider(config: SliderConfig) {
       const vmin = which === 'hi' ? lo : min()
       const vmax = which === 'lo' ? hi : max()
       const label = which === 'lo' ? 'Minimum' : which === 'hi' ? 'Maximum' : (config.ariaLabel?.() ?? 'Value')
+      // Validation ARIA (invalid / required / describedby) from the editor
+      // contract; keep the thumb's own value-oriented aria-label.
+      const va = editorAria({
+        id: config.id?.(),
+        invalid: config.invalid?.(),
+        required: config.required?.(),
+        error: config.error?.(),
+        hint: config.hint?.(),
+      })
       return {
         role: 'slider' as const,
         tabindex: disabled() ? -1 : 0,
@@ -162,6 +179,9 @@ export function createSlider(config: SliderConfig) {
         'aria-label': label,
         'aria-orientation': (isVert() ? 'vertical' : 'horizontal') as SliderOrientation,
         'aria-disabled': disabled() || undefined,
+        'aria-invalid': va['aria-invalid'],
+        'aria-required': va['aria-required'],
+        'aria-describedby': va['aria-describedby'],
         onkeydown: (e: KeyboardEvent) => onThumbKey(e, which),
       }
     },

package/src/createTooltip.svelte.ts

@@ -1,9 +1,10 @@
 /**
  * createTooltip - the HEADLESS core behind <SvTooltip>: the hover/focus open
- * state machine with a show delay, Escape-to-hide, and the `aria-describedby` /
- * `role="tooltip"` wiring - as prop-getters you spread onto your own anchor and
- * tooltip elements. No styles, no positioning (that is a DOM concern the renderer
- * owns), like `createListbox`.
+ * state machine with a show delay, an optional close delay, a shared delay-group
+ * (so moving between grouped tooltips skips the re-delay), Escape-to-hide, and the
+ * `aria-describedby` / `role="tooltip"` wiring - as prop-getters you spread onto
+ * your own anchor and tooltip elements. No styles, no positioning (that is a DOM
+ * concern the renderer owns), like `createListbox`.
  *
  * ```svelte
  * <script lang="ts">
@@ -25,6 +26,14 @@ export type TooltipConfig = {
   disabled?: () => boolean
   /** Show delay in ms after hover/focus. Default 300. */
   delay?: () => number
+  /** Hide delay in ms after leave/blur. Default 0. Give it room for interactive tips. */
+  closeDelay?: () => number
+  /**
+   * Delay-group id. Tooltips sharing a group open INSTANTLY while any group
+   * member is open or was open within a short grace window - so scanning a
+   * toolbar of icon buttons does not re-wait the show delay each time.
+   */
+  group?: () => string | undefined
 }
 
 export type TooltipAnchorProps = {
@@ -40,20 +49,65 @@ export type TooltipProps = {
   role: 'tooltip'
 }
 
+/** Grace window (ms) after a group tooltip closes during which the next opens instantly. */
+const GROUP_SKIP_WINDOW = 300
+type GroupEntry = { openCount: number; lastCloseAt: number }
+const groupRegistry = new Map<string, GroupEntry>()
+function groupEntry(id: string): GroupEntry {
+  let e = groupRegistry.get(id)
+  if (!e) { e = { openCount: 0, lastCloseAt: 0 }; groupRegistry.set(id, e) }
+  return e
+}
+const now = () => (typeof Date !== 'undefined' ? Date.now() : 0)
+
 export function createTooltip(config: TooltipConfig = {}) {
   const id = nextEditorId('sv-tip')
   let open = $state(false)
   let showTimer: ReturnType<typeof setTimeout> | undefined
+  let hideTimer: ReturnType<typeof setTimeout> | undefined
+  let counted = false // whether this instance is currently counted in its group
+
+  function groupId() { return config.group?.() }
+
+  /** Effective show delay: 0 when the group is warm (a member open / just closed). */
+  function effectiveDelay(): number {
+    const base = config.delay?.() ?? 300
+    const g = groupId()
+    if (!g) return base
+    const e = groupEntry(g)
+    if (e.openCount > 0 || now() - e.lastCloseAt < GROUP_SKIP_WINDOW) return 0
+    return base
+  }
+
+  function markOpen() {
+    open = true
+    const g = groupId()
+    if (g && !counted) { counted = true; groupEntry(g).openCount++ }
+  }
+  function reallyHide() {
+    open = false
+    clearTimeout(showTimer)
+    clearTimeout(hideTimer)
+    const g = groupId()
+    if (g && counted) { counted = false; const e = groupEntry(g); e.openCount--; e.lastCloseAt = now() }
+  }
 
   function show() {
     if ((config.disabled?.() ?? false) || !(config.text?.() ?? '')) return
+    clearTimeout(hideTimer)
+    if (open) return
     clearTimeout(showTimer)
-    showTimer = setTimeout(() => { open = true }, config.delay?.() ?? 300)
+    showTimer = setTimeout(markOpen, effectiveDelay())
   }
-  function hide() {
+  /** Delayed hide (honors `closeDelay`) - used by pointer/focus leave. */
+  function scheduleHide() {
     clearTimeout(showTimer)
-    open = false
+    const cd = config.closeDelay?.() ?? 0
+    if (cd > 0 && open) { clearTimeout(hideTimer); hideTimer = setTimeout(reallyHide, cd) }
+    else reallyHide()
   }
+  /** Immediate hide - used by Escape and imperative callers. */
+  function hide() { reallyHide() }
 
   // Escape hides the tooltip while it is open (WAI-ARIA tooltip pattern).
   $effect(() => {
@@ -69,14 +123,18 @@ export function createTooltip(config: TooltipConfig = {}) {
     tipId: id,
     show,
     hide,
+    /** Keep an interactive tip open while the pointer is over it. */
+    keepOpen: show,
+    /** Delayed hide honoring `closeDelay` (pointer/focus leave). */
+    scheduleHide,
     /** Spread onto the anchor/trigger wrapper. Also mirror `tipId` onto the real
      *  focusable child's `aria-describedby` so AT announces it on focus. */
     anchorProps: (): TooltipAnchorProps => ({
       'aria-describedby': open ? id : undefined,
       onpointerenter: show,
-      onpointerleave: hide,
+      onpointerleave: scheduleHide,
       onfocusin: show,
-      onfocusout: hide,
+      onfocusout: scheduleHide,
     }),
     /** Spread onto the tooltip element. */
     tooltipProps: (): TooltipProps => ({ id, role: 'tooltip' }),

package/src/editor-contract.ts

@@ -12,6 +12,22 @@
 
 export type EditorSize = 'sm' | 'md' | 'lg'
 
+/**
+ * A small action button rendered inside a framed field (via `SvField`'s
+ * `actions`) - the generalized form of the clear / reveal buttons, for a lookup,
+ * a generate, a copy, etc. `icon` is a Svelte snippet; when absent the `label`
+ * text is shown. (Type-only Svelte import, so this module stays runtime-free.)
+ */
+export type EditorAction = {
+  /** Accessible name + tooltip for the button. */
+  label: string
+  /** Invoked when the button is pressed. */
+  onClick: () => void
+  /** Optional icon snippet; falls back to the `label` text. */
+  icon?: import('svelte').Snippet
+  disabled?: boolean
+}
+
 /** Text direction. `'auto'` defers to the surrounding document/CSS. */
 export type EditorDir = 'ltr' | 'rtl' | 'auto'
 

package/src/export-provider.ts

@@ -0,0 +1,40 @@
+/**
+ * export-provider seam. The free grid ships built-in text export (CSV / TSV /
+ * JSON via the api) but the rich Excel / PDF / HTML export engine lives in
+ * `@svgrid/enterprise`. `aiExport` (a free, built-in AI feature) plans an export
+ * and, when it needs to actually WRITE an enterprise format, delegates to the
+ * engine registered here. Enterprise registers `exportGrid` at install time; if
+ * it is absent, `aiExport` returns the plan without running the download.
+ *
+ * ```ts
+ * // in @svgrid/enterprise, at install:
+ * import { registerExportProvider } from '@svgrid/grid'
+ * import { exportGrid } from './export'
+ * registerExportProvider(exportGrid)
+ * ```
+ */
+import type { SvGridApi } from './index'
+
+export type GridExportRunOptions = {
+  format: string
+  filename?: string
+  rows?: ReadonlyArray<Record<string, unknown>>
+  groupBy?: string[]
+}
+
+export type GridExportProvider = (
+  api: SvGridApi<any, any>,
+  opts: GridExportRunOptions,
+) => Promise<unknown>
+
+let provider: GridExportProvider | null = null
+
+/** Register the export engine that runs AI-planned exports. Enterprise calls this. */
+export function registerExportProvider(fn: GridExportProvider | null): void {
+  provider = fn
+}
+
+/** The registered export engine, or null when @svgrid/enterprise is not installed. */
+export function getExportProvider(): GridExportProvider | null {
+  return provider
+}

package/src/filter-operators.ts

@@ -118,3 +118,40 @@ export function operatorLabelFor<TData extends RowData>(
   }
   return option.label;
 }
+
+/** GridMessages key for each operator's label (see grid-messages.ts). */
+const OPERATOR_MESSAGE_KEY: Record<FilterOperator, string> = {
+  contains: "opContains",
+  notContains: "opNotContains",
+  equals: "opEquals",
+  notEquals: "opNotEquals",
+  startsWith: "opStartsWith",
+  endsWith: "opEndsWith",
+  regex: "opRegex",
+  in: "opIn",
+  notIn: "opNotIn",
+  greaterThan: "opGreaterThan",
+  lessThan: "opLessThan",
+  between: "opBetween",
+  isBlank: "opIsBlank",
+  isNotBlank: "opIsNotBlank",
+};
+
+/**
+ * Localized operator label: honors date `Before`/`After` relabels, then the
+ * `localeText` override for the operator, falling back to the English
+ * `option.label`. `messages` is a loose string map to avoid a type cycle.
+ */
+export function localizeOperatorLabel<TData extends RowData>(
+  option: FilterOption,
+  column: Column<TData> | undefined,
+  messages?: Record<string, string> | null,
+): string {
+  const editorType = column?.columnDef.editorType;
+  if (editorType === "date" || editorType === "datetime") {
+    if (option.value === "lessThan") return messages?.opBefore || "Before";
+    if (option.value === "greaterThan") return messages?.opAfter || "After";
+  }
+  const key = OPERATOR_MESSAGE_KEY[option.value];
+  return (key && messages?.[key]) || option.label;
+}

package/src/form-field.ts

@@ -8,7 +8,9 @@ import type { Validator } from './validators'
  */
 export type FormFieldType =
   | 'text' | 'email' | 'tel' | 'textarea' | 'number' | 'password'
-  | 'select' | 'checkbox' | 'switch' | 'date' | 'color' | 'rating'
+  | 'select' | 'multiselect' | 'checkbox' | 'switch' | 'date' | 'color' | 'rating'
+  | 'radio' | 'slider' | 'tags' | 'phone' | 'country' | 'mask'
+  | 'datetime' | 'time' | 'daterange' | 'combobox' | 'file'
   | 'array'
 
 export type FormField = {
@@ -16,8 +18,44 @@ export type FormField = {
   label: string
   type?: FormFieldType
   required?: boolean
+  /** Show the field but block edits (still submitted, unlike hidden fields). */
+  readonly?: boolean
+  /** Helper text shown under the control (distinct from a validation error). */
+  help?: string
   placeholder?: string
-  options?: Array<{ value: string | number; label: string; color?: string }>
+  /**
+   * Options for select/combobox/radio/multiselect. A function makes them CASCADE:
+   * the list is derived from the current form values (e.g. cities for the picked
+   * country). Pair with `dependsOn` so the child clears when the parent changes.
+   */
+  options?:
+    | Array<{ value: string | number; label: string; color?: string }>
+    | ((values: Record<string, any>) => Array<{ value: string | number; label: string; color?: string }>)
+  /** Field name(s) this one depends on; when a parent changes, this field's value
+   *  is cleared (cascading selects). */
+  dependsOn?: string | string[]
+  /** Mask pattern for `type: 'mask'` (`#`=digit, `A`=letter, `*`=alnum). */
+  mask?: string
+  /** Numeric bounds for `type: 'number'` / `'slider'`. */
+  min?: number
+  max?: number
+  step?: number
+  precision?: number
+  /** Text affixes for `type: 'number'` (e.g. `$` / `%`). */
+  prefix?: string
+  suffix?: string
+  /** Remote option loader for `type: 'combobox'` (debounced typeahead). The
+   *  current form `values` are passed so it can depend on other fields. */
+  loadOptions?: (query: string, values: Record<string, any>) => Promise<Array<{ value: string | number; label: string }>>
+  /** File input hints for `type: 'file'`. */
+  accept?: string
+  multiple?: boolean
+  /**
+   * Derive this field's value from the other form values (e.g. a total). A
+   * computed field is read-only, recomputes reactively, is not user-validated,
+   * and its derived value is included in the submitted payload.
+   */
+  computed?: (values: Record<string, any>) => any
   /** Declarative validation rules (see `rules` - email/pattern/min/compare...). */
   rules?: ReadonlyArray<Validator>
   /** Return an error message, or null/undefined when valid. */
@@ -33,6 +71,8 @@ export type FormField = {
   asyncDebounce?: number
   /** Span full width in the grid. */
   full?: boolean
+  /** Columns to span (generalizes `full`); `2`+ widens the field in a grid. */
+  span?: number
   /**
    * Show the field only when this is `true` / returns `true` (default: always).
    * A field derived from other values, e.g. `visible: (v) => v.hasAddress`.

package/src/grid-messages.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { defaultGridMessages, resolveGridMessages } from './grid-messages'
+
+describe('resolveGridMessages', () => {
+  it('returns the full English defaults when no overrides are given', () => {
+    expect(resolveGridMessages()).toEqual(defaultGridMessages)
+    expect(resolveGridMessages(null)).toEqual(defaultGridMessages)
+    expect(resolveGridMessages({})).toEqual(defaultGridMessages)
+  })
+
+  it('replaces only the provided keys, keeping English for the rest', () => {
+    const m = resolveGridMessages({ noRows: 'Aucune ligne', pageSize: 'Taille :' })
+    expect(m.noRows).toBe('Aucune ligne')
+    expect(m.pageSize).toBe('Taille :')
+    // untouched keys stay English
+    expect(m.columns).toBe('Columns')
+    expect(m.opContains).toBe('Contains')
+  })
+
+  it('falls back to the default for empty-string overrides', () => {
+    const m = resolveGridMessages({ noRows: '' })
+    expect(m.noRows).toBe(defaultGridMessages.noRows)
+  })
+})

package/src/grid-messages.ts

@@ -0,0 +1,137 @@
+/**
+ * Grid chrome localization. Every user-visible UI string the grid renders itself
+ * (empty state, tool panel, pager, status bar, group labels, filter operators,
+ * context-menu items, upsell notes) lives here as a flat message map with English
+ * defaults. Pass `localeText` on `<SvGrid>` to override any subset; unset keys
+ * fall back to English, so omitting `localeText` is a no-op.
+ *
+ * This mirrors the editor kit's `resolveMessages` pattern (editor-contract.ts) so
+ * chrome and editors share one localization idiom.
+ */
+import { resolveMessages } from './editor-contract'
+
+/** Every localizable chrome string, grouped by area in the comments. */
+export type GridMessages = {
+  // Empty / loading state
+  noRows: string
+  loading: string
+  // Tool panel
+  columns: string
+  filters: string
+  clearFilter: string
+  // Pagination
+  pageSize: string
+  page: string
+  of: string
+  firstPage: string
+  prevPage: string
+  nextPage: string
+  lastPage: string
+  // Status bar aggregate labels
+  statCount: string
+  statSum: string
+  statAvg: string
+  statMin: string
+  statMax: string
+  // Grouping chrome
+  group: string
+  grandTotal: string
+  total: string
+  rowsSuffix: string
+  rowSuffix: string
+  // Filter operator labels (mirror filterOperatorOptions ids)
+  opContains: string
+  opNotContains: string
+  opEquals: string
+  opNotEquals: string
+  opStartsWith: string
+  opEndsWith: string
+  opRegex: string
+  opIn: string
+  opNotIn: string
+  opGreaterThan: string
+  opLessThan: string
+  opBetween: string
+  opIsBlank: string
+  opIsNotBlank: string
+  // Date-column relabels for less/greater than
+  opBefore: string
+  opAfter: string
+  // Context menu
+  menuCopy: string
+  menuCut: string
+  menuPaste: string
+  menuClear: string
+  menuInsertRowAbove: string
+  menuInsertRowBelow: string
+  menuRemoveRow: string
+  menuRemoveColumn: string
+  menuEditComment: string
+  chartRange: string
+  // Upsell notes (enterprise views not installed)
+  pivotUpsellTitle: string
+  pivotUpsellBody: string
+}
+
+/** English defaults - the literal strings the grid shipped before localization. */
+export const defaultGridMessages: GridMessages = {
+  noRows: 'No rows to display.',
+  loading: 'Loading grid data...',
+  columns: 'Columns',
+  filters: 'Filters',
+  clearFilter: 'Clear filter',
+  pageSize: 'Page Size:',
+  page: 'Page',
+  of: 'of',
+  firstPage: 'First page',
+  prevPage: 'Previous page',
+  nextPage: 'Next page',
+  lastPage: 'Last page',
+  statCount: 'Count',
+  statSum: 'Sum',
+  statAvg: 'Avg',
+  statMin: 'Min',
+  statMax: 'Max',
+  group: 'Group',
+  grandTotal: 'Grand total',
+  total: 'Total',
+  rowsSuffix: 'rows',
+  rowSuffix: 'row',
+  menuCopy: 'Copy',
+  menuCut: 'Cut',
+  menuPaste: 'Paste',
+  menuClear: 'Clear',
+  menuInsertRowAbove: 'Insert row above',
+  menuInsertRowBelow: 'Insert row below',
+  menuRemoveRow: 'Remove row',
+  menuRemoveColumn: 'Remove column',
+  menuEditComment: 'Edit comment',
+  opContains: 'Contains',
+  opNotContains: 'Not contains',
+  opEquals: 'Equals',
+  opNotEquals: 'Not equals',
+  opStartsWith: 'Starts with',
+  opEndsWith: 'Ends with',
+  opRegex: 'Regex',
+  opIn: 'In',
+  opNotIn: 'Not in',
+  opGreaterThan: 'Greater than',
+  opLessThan: 'Less than',
+  opBetween: 'Between',
+  opIsBlank: 'Blank',
+  opIsNotBlank: 'Not blank',
+  opBefore: 'Before',
+  opAfter: 'After',
+  chartRange: 'Chart selected range',
+  pivotUpsellTitle: 'Pivot mode',
+  pivotUpsellBody: 'Pivot mode is an Enterprise feature. Install @svgrid/enterprise and call enablePivot() to use it.',
+}
+
+/**
+ * Merge a consumer's `localeText` over the English defaults. Undefined/empty
+ * values fall back to the default (via `resolveMessages`), so a partial map only
+ * replaces the keys it sets.
+ */
+export function resolveGridMessages(overrides?: Partial<GridMessages> | null): GridMessages {
+  return resolveMessages(defaultGridMessages, overrides)
+}

package/src/group-display.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { buildAutoGroupColumns, insertGroupFooters } from './group-display'
+
+type R = { id: string; depth: number; group?: boolean; total?: number; footer?: boolean }
+
+const rows: R[] = [
+  { id: 'gA', depth: 0, group: true, total: 30 },
+  { id: 'a1', depth: 1 },
+  { id: 'a2', depth: 1 },
+  { id: 'gB', depth: 0, group: true, total: 20 },
+  { id: 'b1', depth: 1 },
+]
+
+const opts = {
+  getDepth: (r: R) => r.depth,
+  isGroup: (r: R) => !!r.group,
+  makeFooter: (g: R): R => ({ id: `${g.id}__footer`, depth: g.depth, footer: true, total: g.total }),
+}
+
+describe('insertGroupFooters', () => {
+  it('is a no-op when no footer flags are set', () => {
+    expect(insertGroupFooters(rows, opts)).toEqual(rows)
+  })
+
+  it('inserts one footer after each group, preserving order', () => {
+    const out = insertGroupFooters(rows, { ...opts, includeGroupFooter: true })
+    expect(out.map((r) => r.id)).toEqual([
+      'gA', 'a1', 'a2', 'gA__footer',
+      'gB', 'b1', 'gB__footer',
+    ])
+    // footers carry the group's aggregate
+    expect(out.find((r) => r.id === 'gA__footer')!.total).toBe(30)
+  })
+
+  it('closes nested groups deepest-first', () => {
+    const nested: R[] = [
+      { id: 'g0', depth: 0, group: true, total: 100 },
+      { id: 'g0a', depth: 1, group: true, total: 60 },
+      { id: 'leaf1', depth: 2 },
+      { id: 'g0b', depth: 1, group: true, total: 40 },
+      { id: 'leaf2', depth: 2 },
+    ]
+    const out = insertGroupFooters(nested, { ...opts, includeGroupFooter: true })
+    expect(out.map((r) => r.id)).toEqual([
+      'g0', 'g0a', 'leaf1', 'g0a__footer',
+      'g0b', 'leaf2', 'g0b__footer', 'g0__footer',
+    ])
+  })
+
+  it('appends a grand-total footer at the end', () => {
+    const out = insertGroupFooters(rows, {
+      ...opts,
+      includeGrandTotalFooter: true,
+      makeGrandTotal: () => ({ id: '__grand', depth: 0, footer: true, total: 50 }),
+    })
+    expect(out[out.length - 1]!.id).toBe('__grand')
+  })
+})
+
+describe('buildAutoGroupColumns', () => {
+  it('returns nothing for groupRows / no grouping', () => {
+    expect(buildAutoGroupColumns(['region'], 'groupRows')).toEqual({ autoColumns: [], hiddenSourceIds: new Set() })
+    expect(buildAutoGroupColumns([], 'singleColumn').autoColumns).toHaveLength(0)
+  })
+
+  it('singleColumn: one combined auto column, all grouped columns hidden', () => {
+    const r = buildAutoGroupColumns(['region', 'category'], 'singleColumn')
+    expect(r.autoColumns).toEqual([{ id: '__autoGroup', field: null, level: 0 }])
+    expect([...r.hiddenSourceIds].sort()).toEqual(['category', 'region'])
+  })
+
+  it('multipleColumns: one auto column per grouped field', () => {
+    const r = buildAutoGroupColumns(['region', 'category'], 'multipleColumns')
+    expect(r.autoColumns.map((c) => c.id)).toEqual(['__group_region', '__group_category'])
+    expect(r.autoColumns.map((c) => c.field)).toEqual(['region', 'category'])
+  })
+})