@svgrid/grid 1.2.34 → 2.0.0

package/src/keyboard-handlers.ts

@@ -245,6 +245,26 @@ export function createKeyboard<
     }
     event.preventDefault();
 
+    // Server-side group / tree navigation, built into the grid: ArrowRight
+    // expands a collapsed group row, ArrowLeft collapses an expanded one,
+    // instead of moving the active cell (treegrid-style). Leaves fall through
+    // to normal navigation.
+    const serverGroup = ctx.props.serverGroup;
+    if (serverGroup && (intent === "moveRight" || intent === "moveLeft")) {
+      const data = ctx.allRows[current.rowIndex]?.original;
+      if (data !== undefined && serverGroup.isGroup(data)) {
+        const expanded = serverGroup.expanded?.(data) ?? false;
+        if (intent === "moveRight" && !expanded) {
+          serverGroup.onToggle(data);
+          return;
+        }
+        if (intent === "moveLeft" && expanded) {
+          serverGroup.onToggle(data);
+          return;
+        }
+      }
+    }
+
     if (intent === "clearCells") {
       // Excel `Delete` - clear contents of every cell in the selection
       // (or the active cell if no range). Formatting is left alone, only

package/src/keyboard.test.ts

@@ -1,59 +1,59 @@
-import { describe, expect, it } from 'vitest'
-import { getKeyboardIntent, getNextActiveCell } from './keyboard'
-
-describe('keyboard navigation engine', () => {
-  it('maps keys to navigation intents', () => {
-    expect(getKeyboardIntent(new KeyboardEvent('keydown', { key: 'ArrowLeft' }))).toBe(
-      'moveLeft',
-    )
-    expect(getKeyboardIntent(new KeyboardEvent('keydown', { key: 'Home', ctrlKey: true }))).toBe(
-      'gridStart',
-    )
-    expect(getKeyboardIntent(new KeyboardEvent('keydown', { key: ' ' }))).toBe(
-      'activate',
-    )
-  })
-
-  it('computes next active cell within bounds', () => {
-    const next = getNextActiveCell(
-      { rowIndex: 1, colIndex: 1, cellId: null },
-      'moveDown',
-      { maxRow: 2, maxCol: 3, pageSize: 10 },
-    )
-    expect(next.rowIndex).toBe(2)
-    expect(next.colIndex).toBe(1)
-  })
-
-  it('handles row and grid boundary intents', () => {
-    const rowEnd = getNextActiveCell(
-      { rowIndex: 2, colIndex: 1, cellId: null },
-      'rowEnd',
-      { maxRow: 2, maxCol: 4, pageSize: 2 },
-    )
-    expect(rowEnd.colIndex).toBe(4)
-
-    const gridStart = getNextActiveCell(
-      { rowIndex: 2, colIndex: 4, cellId: null },
-      'gridStart',
-      { maxRow: 2, maxCol: 4, pageSize: 2 },
-    )
-    expect(gridStart.rowIndex).toBe(0)
-    expect(gridStart.colIndex).toBe(0)
-  })
-
-  it('clamps page navigation to valid bounds', () => {
-    const pageUp = getNextActiveCell(
-      { rowIndex: 1, colIndex: 0, cellId: null },
-      'pageUp',
-      { maxRow: 20, maxCol: 2, pageSize: 10 },
-    )
-    const pageDown = getNextActiveCell(
-      { rowIndex: 18, colIndex: 0, cellId: null },
-      'pageDown',
-      { maxRow: 20, maxCol: 2, pageSize: 10 },
-    )
-
-    expect(pageUp.rowIndex).toBe(0)
-    expect(pageDown.rowIndex).toBe(20)
-  })
-})
+import { describe, expect, it } from 'vitest'
+import { getKeyboardIntent, getNextActiveCell } from './keyboard'
+
+describe('keyboard navigation engine', () => {
+  it('maps keys to navigation intents', () => {
+    expect(getKeyboardIntent(new KeyboardEvent('keydown', { key: 'ArrowLeft' }))).toBe(
+      'moveLeft',
+    )
+    expect(getKeyboardIntent(new KeyboardEvent('keydown', { key: 'Home', ctrlKey: true }))).toBe(
+      'gridStart',
+    )
+    expect(getKeyboardIntent(new KeyboardEvent('keydown', { key: ' ' }))).toBe(
+      'activate',
+    )
+  })
+
+  it('computes next active cell within bounds', () => {
+    const next = getNextActiveCell(
+      { rowIndex: 1, colIndex: 1, cellId: null },
+      'moveDown',
+      { maxRow: 2, maxCol: 3, pageSize: 10 },
+    )
+    expect(next.rowIndex).toBe(2)
+    expect(next.colIndex).toBe(1)
+  })
+
+  it('handles row and grid boundary intents', () => {
+    const rowEnd = getNextActiveCell(
+      { rowIndex: 2, colIndex: 1, cellId: null },
+      'rowEnd',
+      { maxRow: 2, maxCol: 4, pageSize: 2 },
+    )
+    expect(rowEnd.colIndex).toBe(4)
+
+    const gridStart = getNextActiveCell(
+      { rowIndex: 2, colIndex: 4, cellId: null },
+      'gridStart',
+      { maxRow: 2, maxCol: 4, pageSize: 2 },
+    )
+    expect(gridStart.rowIndex).toBe(0)
+    expect(gridStart.colIndex).toBe(0)
+  })
+
+  it('clamps page navigation to valid bounds', () => {
+    const pageUp = getNextActiveCell(
+      { rowIndex: 1, colIndex: 0, cellId: null },
+      'pageUp',
+      { maxRow: 20, maxCol: 2, pageSize: 10 },
+    )
+    const pageDown = getNextActiveCell(
+      { rowIndex: 18, colIndex: 0, cellId: null },
+      'pageDown',
+      { maxRow: 20, maxCol: 2, pageSize: 10 },
+    )
+
+    expect(pageUp.rowIndex).toBe(0)
+    expect(pageDown.rowIndex).toBe(20)
+  })
+})

package/src/keyboard.ts

@@ -1,97 +1,97 @@
-import type { ActiveCellState } from './core'
-
-export type GridKeyboardIntent =
-  | 'moveLeft'
-  | 'moveRight'
-  | 'moveUp'
-  | 'moveDown'
-  | 'tabNext'
-  | 'tabPrev'
-  | 'rowStart'
-  | 'rowEnd'
-  | 'gridStart'
-  | 'gridEnd'
-  | 'pageUp'
-  | 'pageDown'
-  | 'activate'
-  | 'clearCells'
-  | 'noop'
-
-export function getKeyboardIntent(event: KeyboardEvent): GridKeyboardIntent {
-  // Ctrl+Home / Ctrl+End come before plain Home / End so the modifier wins.
-  if (event.ctrlKey && event.key === 'Home') return 'gridStart'
-  if (event.ctrlKey && event.key === 'End') return 'gridEnd'
-
-  if (event.key === 'ArrowLeft') return 'moveLeft'
-  if (event.key === 'ArrowRight') return 'moveRight'
-  if (event.key === 'ArrowUp') return 'moveUp'
-  if (event.key === 'ArrowDown') return 'moveDown'
-  if (event.key === 'Home') return 'rowStart'
-  if (event.key === 'End') return 'rowEnd'
-  if (event.key === 'PageUp') return 'pageUp'
-  if (event.key === 'PageDown') return 'pageDown'
-
-  // Excel-style data-entry navigation:
-  //   Enter      → move down (Shift+Enter → up)
-  //   Tab        → move right (Shift+Tab → left), wraps at row boundaries
-  //   Delete     → clear contents of the selected cells
-  //   F2 / Space → start editing the active cell
-  if (event.key === 'Enter') return event.shiftKey ? 'moveUp' : 'moveDown'
-  if (event.key === 'Tab') return event.shiftKey ? 'tabPrev' : 'tabNext'
-  if (event.key === 'F2') return 'activate'
-  if (event.key === ' ') return 'activate'
-  if (event.key === 'Delete') return 'clearCells'
-
-  return 'noop'
-}
-
-export function getNextActiveCell(
-  current: ActiveCellState,
-  intent: GridKeyboardIntent,
-  bounds: { maxRow: number; maxCol: number; pageSize?: number },
-): ActiveCellState {
-  const pageSize = bounds.pageSize ?? 10
-  let rowIndex = current.rowIndex
-  let colIndex = current.colIndex
-
-  if (intent === 'moveLeft') colIndex -= 1
-  if (intent === 'moveRight') colIndex += 1
-  if (intent === 'moveUp') rowIndex -= 1
-  if (intent === 'moveDown') rowIndex += 1
-  if (intent === 'tabNext') {
-    // Right one column; if we fall off the right edge, wrap to the
-    // first column of the next row - Excel's "data entry" behavior.
-    colIndex += 1
-    if (colIndex > bounds.maxCol) {
-      colIndex = 0
-      rowIndex += 1
-    }
-  }
-  if (intent === 'tabPrev') {
-    colIndex -= 1
-    if (colIndex < 0) {
-      colIndex = bounds.maxCol
-      rowIndex -= 1
-    }
-  }
-  if (intent === 'rowStart') colIndex = 0
-  if (intent === 'rowEnd') colIndex = bounds.maxCol
-  if (intent === 'gridStart') {
-    rowIndex = 0
-    colIndex = 0
-  }
-  if (intent === 'gridEnd') {
-    rowIndex = bounds.maxRow
-    colIndex = bounds.maxCol
-  }
-  if (intent === 'pageUp') rowIndex -= pageSize
-  if (intent === 'pageDown') rowIndex += pageSize
-
-  rowIndex = Math.min(Math.max(rowIndex, 0), Math.max(bounds.maxRow, 0))
-  colIndex = Math.min(Math.max(colIndex, 0), Math.max(bounds.maxCol, 0))
-  return {
-    rowIndex,
-    colIndex,
-    cellId: current.cellId,
-  }
-}
+import type { ActiveCellState } from './core'
+
+export type GridKeyboardIntent =
+  | 'moveLeft'
+  | 'moveRight'
+  | 'moveUp'
+  | 'moveDown'
+  | 'tabNext'
+  | 'tabPrev'
+  | 'rowStart'
+  | 'rowEnd'
+  | 'gridStart'
+  | 'gridEnd'
+  | 'pageUp'
+  | 'pageDown'
+  | 'activate'
+  | 'clearCells'
+  | 'noop'
+
+export function getKeyboardIntent(event: KeyboardEvent): GridKeyboardIntent {
+  // Ctrl+Home / Ctrl+End come before plain Home / End so the modifier wins.
+  if (event.ctrlKey && event.key === 'Home') return 'gridStart'
+  if (event.ctrlKey && event.key === 'End') return 'gridEnd'
+
+  if (event.key === 'ArrowLeft') return 'moveLeft'
+  if (event.key === 'ArrowRight') return 'moveRight'
+  if (event.key === 'ArrowUp') return 'moveUp'
+  if (event.key === 'ArrowDown') return 'moveDown'
+  if (event.key === 'Home') return 'rowStart'
+  if (event.key === 'End') return 'rowEnd'
+  if (event.key === 'PageUp') return 'pageUp'
+  if (event.key === 'PageDown') return 'pageDown'
+
+  // Excel-style data-entry navigation:
+  //   Enter      → move down (Shift+Enter → up)
+  //   Tab        → move right (Shift+Tab → left), wraps at row boundaries
+  //   Delete     → clear contents of the selected cells
+  //   F2 / Space → start editing the active cell
+  if (event.key === 'Enter') return event.shiftKey ? 'moveUp' : 'moveDown'
+  if (event.key === 'Tab') return event.shiftKey ? 'tabPrev' : 'tabNext'
+  if (event.key === 'F2') return 'activate'
+  if (event.key === ' ') return 'activate'
+  if (event.key === 'Delete') return 'clearCells'
+
+  return 'noop'
+}
+
+export function getNextActiveCell(
+  current: ActiveCellState,
+  intent: GridKeyboardIntent,
+  bounds: { maxRow: number; maxCol: number; pageSize?: number },
+): ActiveCellState {
+  const pageSize = bounds.pageSize ?? 10
+  let rowIndex = current.rowIndex
+  let colIndex = current.colIndex
+
+  if (intent === 'moveLeft') colIndex -= 1
+  if (intent === 'moveRight') colIndex += 1
+  if (intent === 'moveUp') rowIndex -= 1
+  if (intent === 'moveDown') rowIndex += 1
+  if (intent === 'tabNext') {
+    // Right one column; if we fall off the right edge, wrap to the
+    // first column of the next row - Excel's "data entry" behavior.
+    colIndex += 1
+    if (colIndex > bounds.maxCol) {
+      colIndex = 0
+      rowIndex += 1
+    }
+  }
+  if (intent === 'tabPrev') {
+    colIndex -= 1
+    if (colIndex < 0) {
+      colIndex = bounds.maxCol
+      rowIndex -= 1
+    }
+  }
+  if (intent === 'rowStart') colIndex = 0
+  if (intent === 'rowEnd') colIndex = bounds.maxCol
+  if (intent === 'gridStart') {
+    rowIndex = 0
+    colIndex = 0
+  }
+  if (intent === 'gridEnd') {
+    rowIndex = bounds.maxRow
+    colIndex = bounds.maxCol
+  }
+  if (intent === 'pageUp') rowIndex -= pageSize
+  if (intent === 'pageDown') rowIndex += pageSize
+
+  rowIndex = Math.min(Math.max(rowIndex, 0), Math.max(bounds.maxRow, 0))
+  colIndex = Math.min(Math.max(colIndex, 0), Math.max(bounds.maxCol, 0))
+  return {
+    rowIndex,
+    colIndex,
+    cellId: current.cellId,
+  }
+}

package/src/list-option.ts

@@ -13,3 +13,77 @@ export function filterOptions(options: ReadonlyArray<ListOption>, query: string)
   if (!q) return [...options]
   return options.filter((o) => o.label.toLowerCase().includes(q))
 }
+
+/** An option carrying its position in the flat source array (for prop-getters). */
+export type IndexedOption = ListOption & { index: number }
+/** A section of options that share a `group` heading (null = ungrouped). */
+export type OptionGroup = { group: string | null; options: IndexedOption[] }
+
+/**
+ * Bucket options by their `group` heading, preserving each option's flat index
+ * so grouped rendering still drives `optionProps(index)` etc. Groups appear in
+ * first-seen order. When no option sets `group`, the result is a single
+ * `group: null` section (render it flat).
+ */
+export function groupOptions(options: ReadonlyArray<ListOption>): OptionGroup[] {
+  const groups: OptionGroup[] = []
+  const byName = new Map<string | null, OptionGroup>()
+  options.forEach((o, index) => {
+    const key = o.group ?? null
+    let g = byName.get(key)
+    if (!g) { g = { group: key, options: [] }; byName.set(key, g); groups.push(g) }
+    g.options.push({ ...o, index })
+  })
+  return groups
+}
+
+/** Whether any option declares a `group` (so headings are worth rendering). */
+export function hasGroups(options: ReadonlyArray<ListOption>): boolean {
+  return options.some((o) => o.group != null)
+}
+
+/**
+ * Next enabled option index whose label starts with `buffer` (type-ahead),
+ * searching forward from just after `from` and wrapping. Returns -1 for no
+ * match / empty buffer. Case-insensitive.
+ */
+export function nextTypeaheadIndex(
+  options: ReadonlyArray<ListOption>,
+  buffer: string,
+  from: number,
+): number {
+  const b = buffer.trim().toLowerCase()
+  if (!b || !options.length) return -1
+  const n = options.length
+  for (let k = 1; k <= n; k++) {
+    const i = (from + k) % n
+    const o = options[i]
+    if (o && !o.disabled && o.label.toLowerCase().startsWith(b)) return i
+  }
+  return -1
+}
+
+/**
+ * A tiny type-ahead buffer: accumulates printable characters within `timeout`
+ * ms of each other, then resets. Frameworkfree; the caller supplies scheduling.
+ */
+export function createTypeaheadBuffer(timeout = 600) {
+  let buffer = ''
+  let timer: ReturnType<typeof setTimeout> | undefined
+  return {
+    get value() { return buffer },
+    /** Append a character and (re)arm the reset timer. Returns the new buffer. */
+    push(char: string): string {
+      buffer += char
+      if (timer) clearTimeout(timer)
+      timer = setTimeout(() => { buffer = '' }, timeout)
+      return buffer
+    },
+    clear() { buffer = ''; if (timer) clearTimeout(timer) },
+  }
+}
+
+/** Whether a keydown is a bare printable character (a type-ahead candidate). */
+export function isTypeaheadKey(e: KeyboardEvent): boolean {
+  return e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey && e.key !== ' '
+}

package/src/list-power.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Tests for the list "power" features: option grouping (preserving flat index),
+ * type-ahead matching, and their wiring into SvListBox (group headings render;
+ * typing a prefix moves the active option).
+ */
+import { describe, expect, it } from 'vitest'
+import { mount, unmount, flushSync } from 'svelte'
+import SvListBox from './SvListBox.svelte'
+import { groupOptions, hasGroups, nextTypeaheadIndex } from './list-option'
+
+const opts = [
+  { value: 'us', label: 'United States', group: 'Americas' },
+  { value: 'ca', label: 'Canada', group: 'Americas' },
+  { value: 'fr', label: 'France', group: 'Europe' },
+  { value: 'de', label: 'Germany', group: 'Europe' },
+]
+
+describe('groupOptions', () => {
+  it('buckets by group in first-seen order and preserves the flat index', () => {
+    const groups = groupOptions(opts)
+    expect(groups.map((g) => g.group)).toEqual(['Americas', 'Europe'])
+    expect(groups[0].options.map((o) => o.index)).toEqual([0, 1])
+    expect(groups[1].options.map((o) => o.index)).toEqual([2, 3])
+    expect(hasGroups(opts)).toBe(true)
+  })
+  it('returns a single null group when nothing is grouped', () => {
+    const flat = [{ value: 'a', label: 'A' }, { value: 'b', label: 'B' }]
+    expect(groupOptions(flat)).toEqual([{ group: null, options: [{ value: 'a', label: 'A', index: 0 }, { value: 'b', label: 'B', index: 1 }] }])
+    expect(hasGroups(flat)).toBe(false)
+  })
+})
+
+describe('nextTypeaheadIndex', () => {
+  it('finds the next enabled label-prefix match, wrapping from `from`', () => {
+    expect(nextTypeaheadIndex(opts, 'f', -1)).toBe(2)   // France
+    expect(nextTypeaheadIndex(opts, 'g', 2)).toBe(3)    // Germany
+    expect(nextTypeaheadIndex(opts, 'can', 0)).toBe(1)  // Canada
+    expect(nextTypeaheadIndex(opts, 'z', 0)).toBe(-1)   // no match
+    expect(nextTypeaheadIndex(opts, '', 0)).toBe(-1)
+  })
+})
+
+function mountLb(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvListBox, { target, props: props as any })
+  flushSync()
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+
+describe('SvListBox grouping + type-ahead', () => {
+  it('renders group headings above their options', () => {
+    const { target, destroy } = mountLb({ options: opts, value: 'us' })
+    try {
+      const headings = [...target.querySelectorAll('.sv-listbox__group')].map((n) => n.textContent)
+      expect(headings).toEqual(['Americas', 'Europe'])
+      expect(target.querySelectorAll('.sv-listbox__opt')).toHaveLength(4)
+    } finally { destroy() }
+  })
+
+  it('type-ahead moves the active option to a label prefix', () => {
+    const { target, destroy } = mountLb({ options: opts, value: 'us' })
+    try {
+      const list = target.querySelector<HTMLElement>('.sv-listbox')!
+      list.dispatchEvent(new KeyboardEvent('keydown', { key: 'g', bubbles: true }))
+      flushSync()
+      const active = target.querySelector('.sv-listbox__opt.is-active .sv-listbox__label')!
+      expect(active.textContent).toBe('Germany')
+    } finally { destroy() }
+  })
+})