@svgrid/grid 2.6.20 → 2.6.22

package/src/createTree.svelte.ts

@@ -31,6 +31,7 @@ export type TreeNode = {
   lazy?: boolean
 }
 
+/** A node's checkbox state. `'indeterminate'` means some but not all descendants are checked. */
 export type CheckState = 'checked' | 'indeterminate' | 'unchecked'
 
 /** A single visible (flattened) tree row. */
@@ -145,6 +146,7 @@ export type TreeConfig = {
   filter?: () => string | undefined
 }
 
+/** Build the headless tree model: expansion, selection and checkbox cascading, with no markup. */
 export function createTree(config: TreeConfig) {
   const nodes = () => config.nodes()
   const checkable = () => config.checkable?.() ?? false
@@ -316,4 +318,5 @@ export function createTree(config: TreeConfig) {
   }
 }
 
+/** The headless tree instance returned by {@link createTree}. */
 export type Tree = ReturnType<typeof createTree>

package/src/datetime/date-core.ts

@@ -10,6 +10,7 @@
  *   `firstDayOfWeek`.
  */
 
+/** Anything the date helpers accept: a `Date`, epoch milliseconds, or a parseable string. */
 export type DateLike = Date | number | string
 
 /** Coerce a Date | epoch-ms | parseable string to a Date, or null if invalid. */
@@ -137,6 +138,7 @@ export function centuryRange(year: number): { start: number; end: number } {
   return { start, end: start + 99 }
 }
 
+/** One cell of a month grid, including the leading and trailing days from adjacent months. */
 export type MonthMatrixCell = {
   date: Date
   /** In the displayed month (vs. leading/trailing days of adjacent months). */

package/src/datetime/date-restrict.ts

@@ -5,6 +5,7 @@
  */
 import { compareDay, isSameDay, toDate, type DateLike } from './date-core'
 
+/** Which dates a picker allows: bounds, an explicit disabled set, and disabled weekdays. */
 export type RestrictOptions = {
   min?: DateLike | null
   max?: DateLike | null

package/src/datetime/timezone.ts

@@ -12,6 +12,7 @@
  * headless contexts that forbid `Date.now()`).
  */
 
+/** A wall-clock time broken into fields, as it reads in a specific time zone. */
 export type ZoneParts = {
   year: number
   month: number // 1-12

package/src/dock-manager-model.ts

@@ -31,6 +31,7 @@ import {
   type IdGen,
 } from './dock-model'
 
+/** Which edge a pane docks against when dropped. */
 export type DockSide = Exclude<DockZone, 'center'>
 
 /** A floating window: one tabs leaf shown in a movable/resizable frame. */
@@ -58,6 +59,7 @@ export type AutoHideEntry = {
   size: number
 }
 
+/** The whole dock manager: its layout tree plus floating and pinned panes. */
 export type DockManagerState = {
   main: DockNode | null
   floating: FloatWindow[]
@@ -74,6 +76,7 @@ export type PaneLocation =
   | { kind: 'floating'; windowId: string }
   | { kind: 'autoHide'; entryId: string }
 
+/** Find a pane in the layout tree by id, returning it with its parent for mutation. */
 export function locatePane(state: DockManagerState, paneId: string): PaneLocation | null {
   if (state.main && findTabsWithPane(state.main, paneId)) return { kind: 'main' }
   for (const w of state.floating) {

package/src/dock-model.ts

@@ -13,6 +13,7 @@
  * without a browser. Modelled on Smart's `smart-layout` group/item structure.
  */
 
+/** One dockable pane: its id, title, and the state a tab needs to render. */
 export type DockPane = {
   id: string
   title: string
@@ -40,15 +41,18 @@ export type DockGroup = {
   sizes: number[]
 }
 
+/** A node in the layout tree - either a split group or a tabbed leaf. */
 export type DockNode = DockGroup | DockTabs
 
 /** Where a dragged pane lands relative to a target leaf. */
 export type DockZone = 'left' | 'right' | 'top' | 'bottom' | 'center'
 
+/** Supplies ids for newly created nodes, so layouts stay deterministic in tests. */
 export type IdGen = () => string
 
 // ---- construction helpers -------------------------------------------------
 
+/** Build a {@link DockPane}. */
 export function pane(id: string, title: string, closable = true): DockPane {
   return { id, title, closable }
 }
@@ -58,10 +62,12 @@ export function leafMinSize(node: DockTabs): number {
   return node.panes.reduce((m, p) => Math.max(m, p.minSize ?? 0), 0)
 }
 
+/** Build a tabbed leaf holding the given panes. */
 export function tabs(genId: IdGen, panes: DockPane[], active = 0): DockTabs {
   return { type: 'tabs', id: genId(), panes, active: clampIndex(active, panes.length) }
 }
 
+/** Build a split group: panes or nested groups laid out in a row or column. */
 export function group(
   genId: IdGen,
   direction: 'row' | 'column',

package/src/editor-contract.ts

@@ -10,6 +10,7 @@
  * Framework-free (no Svelte, no DOM) so it can be unit-tested and reused.
  */
 
+/** How much room a cell editor asks for, so the grid can size its overlay. */
 export type EditorSize = 'sm' | 'md' | 'lg'
 
 /**

package/src/filtering/excel-filters.ts

@@ -49,12 +49,42 @@ export function normalizeForFilter(
   locale?: string | ReadonlyArray<string>,
 ): string {
   if (!s) return ''
+
+  // Fast path for pure-ASCII input, which is the overwhelming majority of what
+  // a grid filters. Both of the expensive steps are provably no-ops there:
+  // ASCII is already NFD-normalised, and the combining-marks block this strips
+  // (U+0300..U+036F) contains no ASCII. So lowercasing alone is the same
+  // answer, and `normalize-fast-path.test.ts` checks that exhaustively over
+  // every ASCII code point rather than taking the argument on trust.
+  //
+  // Worth the branch: this runs once per cell per filter - 100,000 times for a
+  // one-column filter over a 100k grid - and a CPU profile of a browser filter
+  // put more time in this function than in any other.
+  //
+  // Note the locale still routes through toLocaleLowerCase even on the fast
+  // path: 'I'.toLocaleLowerCase('tr') is 'ı', so ASCII does NOT imply the
+  // locale can be ignored.
+  if (isAsciiOnly(s)) {
+    return locale ? s.toLocaleLowerCase(locale as string | string[]) : s.toLowerCase()
+  }
+
   const stripped = s.normalize('NFD').replace(DIACRITIC_RE, '')
   return locale
     ? stripped.toLocaleLowerCase(locale as string | string[])
     : stripped.toLowerCase()
 }
 
+/**
+ * True when every code unit is ASCII. A plain char-code scan, which is far
+ * cheaper than the `normalize()` + regex pass it lets us skip.
+ */
+function isAsciiOnly(s: string): boolean {
+  for (let i = 0; i < s.length; i++) {
+    if (s.charCodeAt(i) > 127) return false
+  }
+  return true
+}
+
 /**
  * Delimiter used to serialise the `in` / `notIn` value list into the single
  * `value` string that the filter model carries.

package/src/filtering/normalize-fast-path.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Equivalence tests for `normalizeForFilter`'s ASCII fast path.
+ *
+ * The function NFD-decomposes, strips combining marks, then lowercases. It runs
+ * once per cell per filter - 100,000 times for a one-column filter on a 100k
+ * grid - and a CPU profile of a browser filter put 15.5% of the whole operation
+ * inside it, more than any other single function.
+ *
+ * For a pure-ASCII string the first two steps are provably no-ops: ASCII is
+ * already in NFD, and the combining-marks block (U+0300..U+036F) contains no
+ * ASCII. So the fast path returns `lowercase(s)` directly.
+ *
+ * "Provably" is doing a lot of work in that sentence, so the first test checks
+ * it exhaustively over every ASCII code point rather than trusting the argument.
+ */
+import { describe, expect, it } from 'vitest'
+import { normalizeForFilter } from './excel-filters'
+
+/** The original implementation, verbatim, as the oracle. */
+const DIACRITIC_RE = /[̀-ͯ]/g
+function reference(s: string, locale?: string | ReadonlyArray<string>): string {
+  if (!s) return ''
+  const stripped = s.normalize('NFD').replace(DIACRITIC_RE, '')
+  return locale
+    ? stripped.toLocaleLowerCase(locale as string | string[])
+    : stripped.toLowerCase()
+}
+
+describe('normalizeForFilter - ASCII fast path equivalence', () => {
+  it('matches on every single ASCII code point', () => {
+    for (let code = 0; code < 128; code++) {
+      const ch = String.fromCharCode(code)
+      expect(normalizeForFilter(ch), `code point ${code}`).toBe(reference(ch))
+    }
+  })
+
+  it('matches on every ASCII code point under a Turkish locale', () => {
+    // Turkish is the locale that makes ASCII lowercasing locale-dependent:
+    // 'I'.toLocaleLowerCase('tr') is 'ı', not 'i'. The fast path must still
+    // route through toLocaleLowerCase rather than assuming ASCII is safe.
+    for (let code = 0; code < 128; code++) {
+      const ch = String.fromCharCode(code)
+      expect(normalizeForFilter(ch, 'tr'), `code point ${code}`).toBe(reference(ch, 'tr'))
+    }
+  })
+
+  const CASES: Array<[string, string]> = [
+    ['empty', ''],
+    ['plain ascii', 'Hello World'],
+    ['ascii with digits and punctuation', 'ABC-123_x.y,z!'],
+    ['precomposed accents', 'café CAFÉ Café'],
+    ['decomposed accents', 'café'],
+    ['mixed ascii and accents', 'naive naïve NAÏVE'],
+    ['german sharp s', 'straße STRASSE'],
+    ['greek', 'ΣΊΣΥΦΟΣ σίσυφος'],
+    ['cyrillic', 'Привет МИР'],
+    ['cjk', '日本語テキスト'],
+    ['emoji', 'grid 🚀 test'],
+    ['combining marks alone', '̀́̂'],
+    ['ascii then combining mark', 'áb'],
+    ['turkish dotted capital', 'İstanbul ISTANBUL'],
+    ['ligature', 'file flow'],
+    ['fullwidth', 'ＡＢＣ'],
+    ['nbsp and control chars', 'a b\tc\nd'],
+    ['long ascii', 'x'.repeat(500)],
+    ['long with one non-ascii at the end', 'x'.repeat(500) + 'é'],
+  ]
+
+  for (const [name, input] of CASES) {
+    it(`matches: ${name}`, () => {
+      expect(normalizeForFilter(input)).toBe(reference(input))
+    })
+    it(`matches with locale: ${name}`, () => {
+      expect(normalizeForFilter(input, 'tr')).toBe(reference(input, 'tr'))
+      expect(normalizeForFilter(input, 'de')).toBe(reference(input, 'de'))
+    })
+  }
+
+  it('matches across randomised mixed-script strings', () => {
+    let seed = 7
+    const rand = () => {
+      seed = (seed * 1103515245 + 12345) & 0x7fffffff
+      return seed / 0x7fffffff
+    }
+    const pools = [
+      'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 -_.',
+      'áéíóúàèìòùâêîôûäëïöüñçÁÉÍÓÚÑÇ',
+      '̀́̂̃̈',
+      'ΑΒΓΔαβγδ',
+      'абвгдАБВГД',
+      '日本語中文한국어',
+    ]
+    for (let trial = 0; trial < 300; trial++) {
+      let s = ''
+      const len = 1 + Math.floor(rand() * 20)
+      for (let i = 0; i < len; i++) {
+        const pool = pools[Math.floor(rand() * pools.length)]!
+        s += pool[Math.floor(rand() * pool.length)]
+      }
+      expect(normalizeForFilter(s), s).toBe(reference(s))
+      expect(normalizeForFilter(s, 'tr'), s).toBe(reference(s, 'tr'))
+    }
+  })
+})

package/src/group-display.ts

@@ -14,7 +14,7 @@
  * they are trivially unit-testable and carry no dependency on the grid runtime.
  */
 
-/** AG-Grid-style grouping display variants. */
+/** Grouping display variants. */
 export type GroupDisplayType = 'groupRows' | 'singleColumn' | 'multipleColumns'
 
 export type GroupFooterOptions<R> = {

package/src/index.ts

@@ -588,7 +588,13 @@ export {
   type CellBorderSpec,
   type BorderSpec,
 } from './spreadsheet'
+// The two resize actions, exported as a matched pair. `<SvGrid>` drives both
+// through the `rowResize` / `columnResize` props - both default OFF, both are
+// turned on by setting them true, and the grid `import()`s the module itself so
+// a grid that leaves them off carries neither. Import them directly only for a
+// headless table, which renders its own rows and headers.
 export { rowResize, type RowResizeOptions } from './row-resize'
+export { columnResize, type ColumnResizeOptions } from './column-resize'
 export { rowDropZone, type RowDragEndEvent, type RowDropZoneOptions } from './row-drag'
 export { resolveColumnTypes, inferCellDataType, type CellDataType } from './column-types'
 export {
@@ -690,7 +696,12 @@ export { createVirtualizer } from './virtualization/virtualizer'
 export { createSvelteVirtualizer } from './virtualization/svelte-virtualizer.svelte'
 export { createColumnVirtualizer } from './virtualization/column-virtualizer'
 export type { VirtualItem, VirtualizerOptions, VirtualizerState } from './virtualization/types'
-export type { SvGridApi, SvGridFilterOperator, SvGridWrapperProps } from './svgrid-wrapper.types'
+export type {
+  SvGridApi,
+  SvGridFilterOperator,
+  SvGridViewState,
+  SvGridWrapperProps,
+} from './svgrid-wrapper.types'
 export {
   parseEditorValue,
   normalizeEditorOptions,

package/src/list-option.ts

@@ -71,6 +71,7 @@ export type VirtualListRow =
   | { type: 'group'; label: string; size: number }
   | { type: 'option'; opt: IndexedOption; size: number }
 
+/** A flattened option list plus its measurements, for virtualizing long dropdowns. */
 export type FlatVirtualModel = {
   /** Group headings + options in render order, each with its px height. */
   entries: VirtualListRow[]

package/src/menus.ts

@@ -151,7 +151,7 @@ export function createMenus<
   function openChooseColumns(event: MouseEvent) {
     event.stopPropagation();
     // Submenu behavior: keep the parent operations menu open and float the
-    // Choose Columns panel out to the right of it (AG-Grid style). Falls
+    // Choose Columns panel out to the right of it, submenu-style. Falls
     // back to below the item if the popover would clip the viewport.
     const trigger = event.currentTarget as HTMLElement;
     const menuEl = trigger.closest(".sv-grid-menu") as HTMLElement | null;

package/src/positioning.ts

@@ -35,6 +35,7 @@ export type Rect = { x: number; y: number; width: number; height: number }
 /** The available viewport (defaults to `window` in the browser). */
 export type Viewport = { width: number; height: number }
 
+/** Where to put a floating element: its preferred side, offsets, and collision behaviour. */
 export type ComputePositionOptions = {
   /** Preferred placement. Default `'bottom-start'`. */
   placement?: Placement
@@ -58,6 +59,7 @@ export type ComputePositionOptions = {
   minMainAxis?: number
 }
 
+/** The resolved position, including the side actually used after collision handling. */
 export type ComputePositionResult = {
   /** Floating left, in viewport (fixed-position) coordinates. */
   x: number