@svgrid/grid 2.2.26 → 2.2.28

package/README.md

@@ -10,21 +10,29 @@
   <a href="https://www.npmjs.com/package/@svgrid/grid"><img src="https://img.shields.io/npm/v/%40svgrid%2Fgrid.svg?label=%40svgrid%2Fgrid" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/@svgrid/grid"><img src="https://img.shields.io/npm/dm/%40svgrid%2Fgrid.svg" alt="npm downloads" /></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen.svg" alt="MIT License" /></a>
-  <a href="./dist"><img src="https://img.shields.io/badge/types-included-blue.svg" alt="TypeScript" /></a>
+  <a href="https://www.npmjs.com/package/@svgrid/grid"><img src="https://img.shields.io/badge/types-included-blue.svg" alt="TypeScript" /></a>
   <a href="https://svelte.dev"><img src="https://img.shields.io/badge/svelte-5-ff3e00.svg" alt="Svelte 5" /></a>
 </p>
 
 <p align="center">
   <a href="https://svgrid.com">Website</a> ·
-  <a href="https://svgrid.com/docs">Docs</a> ·
-  <a href="https://svgrid.com/demos">280+ Demos</a> ·
-  <a href="https://svgrid.com/pricing">Pricing</a> ·
-  <a href="https://svgrid.com/roadmap">Roadmap</a>
+  <a href="https://svgrid.com/docs/">Docs</a> ·
+  <a href="https://svgrid.com/demos/">370+ Demos</a> ·
+  <a href="https://svgrid.com/pricing/">Pricing</a> ·
+  <a href="https://svgrid.com/roadmap/">Roadmap</a>
 </p>
 
 ---
 
-A production-grade data grid built from the first line for **Svelte 5 runes** - not a React grid wrapped in a Svelte shim. Compose the headless engine yourself, or drop in the full `<SvGrid />` render component and ship. The MIT core has **zero feature gating**: no license key, no watermark, no row-count cap.
+A production-grade **Svelte 5 data grid and data table** built from the first line for **runes**, not a
+React grid wrapped in a Svelte shim. Virtual scrolling over 100k+ rows, Excel-style filtering, inline
+editing, row grouping, tree data, and server-side data. Compose the headless engine yourself, or drop in
+the full `<SvGrid />` render component and ship. The MIT core has **zero feature gating**: no license key,
+no watermark, no row-count cap.
+
+<p align="center">
+  <img src="https://svgrid.com/brand/svgrid-hero.png" alt="A SvGrid trading desk: KPI cards, sector filter chips, and a virtualized data table with sparkline trend columns, conditional colour, and pinned columns." width="100%" />
+</p>
 
 ## Install
 
@@ -61,21 +69,34 @@ npm install @svgrid/grid
 <SvGrid data={rows} columns={columns} />
 ```
 
-That is a real, accessible grid. Sorting, filtering, virtualization, cell selection, and inline editing all wire up the moment you turn on the matching prop.
+That is a real, accessible grid. Sorting, filtering, virtualization, cell selection, and inline editing
+all wire up the moment you turn on the matching prop.
+
+## Quick facts
+
+| | |
+|---|---|
+| **License** | MIT, free for commercial use |
+| **Requires** | `svelte@^5` (peer dependency), Node 16+ |
+| **Bundle (gzip)** | ~2 KB headless core, ~80 KB full `<SvGrid>` + ~9 KB CSS |
+| **Types** | Bundled, no `@types/` package needed |
+| **Module format** | ESM, plus a CDN build at `@svgrid/grid/cdn` |
+| **SSR** | Works under SvelteKit SSR and static builds |
+| **Theming** | `--sg-*` CSS custom properties, dark mode + high contrast |
 
 ## Capabilities
 
-- **Virtualization** - row + column windowing; 100k x 100 stays smooth, with a 1M-row demo.
+- **Virtual scrolling** - row + column windowing; 100k x 100 stays smooth, with a 1M-row demo.
 - **Filtering** - Excel-style filter menu, inline filter row, set / value-list filter, locale-aware matching, between operators.
 - **Editing** - 14 built-in `editorType`s (text, number, date, datetime, time, select, rich-select with typeahead, textarea, color, checkbox, list, chips, rating, password) plus a `cellEditor` snippet slot for anything custom.
 - **Selection** - cell-range click+drag and Shift+arrows, copy/paste as TSV, Excel-style fill handle, row selection.
-- **Views** - native Kanban board mode (drag cards between lanes), row grouping with aggregation, tree data, master/detail, full-width detail rows.
-- **Layout** - row + column pinning, sticky header + first column, header drag-to-reorder, autosize, keyboard-accessible column sizing, zebra rows.
+- **Views** - row grouping with aggregation, tree data, master/detail, full-width detail rows, spreadsheet mode with formulas.
+- **Layout** - row + column pinning, sticky header + first column, header drag-to-reorder, autosize, keyboard-accessible column sizing, zebra rows, responsive mode.
 - **Data operations** - find in grid (Ctrl+F), undo / redo, transaction API, optimistic updates, server-side row model with sort / filter / group pushdown.
-- **UI components** - a Svelte 5 component suite ships in the package (inputs, selection, date/time, overlays, layout, feedback) - standalone or as grid cell editors.
+- **AI helpers, free** - natural-language filter, smart fill, summarize, classify, anomaly detection, and "chart this". Model-agnostic: register one provider, nothing is bundled.
+- **UI components** - a Svelte 5 component suite ships in the package (inputs, selection, date/time, overlays, layout, feedback), standalone or as grid cell editors.
 - **Accessibility** - WAI-ARIA grid roles, full keyboard navigation, RTL, high-contrast theme.
 - **Engineered for production** - first-class TypeScript types, CSP / Trusted-Types safe rendering, SSR-friendly, themeable via `--sg-*` CSS tokens.
-- **Lean** - ~2 KB gzipped headless core, ~77 KB gzipped full grid (+ ~9 KB CSS); charts, cell editors and export load on demand as their own chunks, and the Kanban board + scheduler are Enterprise views. Svelte stays a peer dependency.
 
 ## Headless or render-ready
 
@@ -109,37 +130,70 @@ import {
 } from '@svgrid/grid'
 ```
 
-- **Headless** - drive `createSvGrid` and the row-model factories, render your own markup. `getGrid*A11yProps` helpers keep custom markup accessible.
+- **Headless** - drive `createSvGrid` and the row-model factories, render your own markup.
+  `getGrid*A11yProps` helpers keep custom markup accessible. About 2 KB gzipped.
 - **Render-ready** - `<SvGrid />` is a complete, accessible, themeable grid you configure with props.
 
-Compatibility aliases are provided for the framework-neutral names: `createGrid`, `createGridState`, `subscribeGrid`.
+Compatibility aliases are provided for the framework-neutral names: `createGrid`, `createGridState`,
+`subscribeGrid`.
 
 ## AI-native
 
-SvGrid publishes an [MCP server](https://www.npmjs.com/package/@svgrid/mcp) and `llms.txt` / `llms-full.txt`, so Claude, Cursor, and Zed answer with accurate, version-pinned APIs and all 280+ demo sources as context - not hallucinated methods.
+SvGrid publishes an [MCP server](https://www.npmjs.com/package/@svgrid/mcp) plus
+[llms.txt](https://svgrid.com/llms.txt) and [llms-full.txt](https://svgrid.com/llms-full.txt), so Claude,
+Cursor, and Zed answer with accurate, version-pinned APIs and all 370+ demo sources as context rather
+than hallucinated methods.
+
+```bash
+claude mcp add svgrid -- npx -y @svgrid/mcp
+npx skills add sv-grid/sv-grid    # always-on house-style rules
+```
+
+See [Use sv-grid docs as LLM context](https://svgrid.com/docs/help/llm-grounding/).
 
 ## Enterprise features
 
-The MIT core is free for any use, including commercial, with **no feature gating** - sorting, filtering, editing, virtualization, and the **server-side row model** (sort / filter / group pushdown) all ship in the free package. The optional [`@svgrid/enterprise`](https://www.npmjs.com/package/@svgrid/enterprise) pack layers on the export- and analytics-heavy features teams tend to need last:
+The MIT core is free for any use, including commercial, with **no feature gating**. Sorting, filtering,
+editing, virtualization, the **server-side row model**, and the **AI helpers** all ship in the free
+package. The optional [`@svgrid/enterprise`](https://www.npmjs.com/package/@svgrid/enterprise) pack layers
+on the export- and analytics-heavy features teams tend to need last:
 
 - **Excel / PDF / CSV / TSV / HTML export** plus paginated print.
+- **Excel / CSV / TSV / JSON import** with auto-mapping and per-row validation.
 - **Pivot tables** with a drag-and-drop pivot Designer.
-- **Scheduler / calendar view** and Kanban roll-ups for larger deployments.
-- **AI helpers** and SvGrid Studio for data-app scaffolding.
+- **Kanban board and scheduler / calendar renderers** for the `board` and `scheduler` props.
+
+OSS projects receive an Enterprise key free. See [Pricing](https://svgrid.com/pricing/).
+
+## Comparison
+
+| | SvGrid | AG Grid Community | TanStack Table |
+|---|---|---|---|
+| **Svelte 5 runes native** | Yes | No, JS core + wrapper | Adapter only |
+| **Ships a renderer** | Yes, plus headless | Yes | No, headless only |
+| **Bundle (gzip)** | ~2 KB headless / ~80 KB full | ~340 KB | ~12-14 KB |
+| **Master/detail, tree, range selection** | Free | Enterprise only | Build it yourself |
 
-OSS projects receive an Enterprise key free. See the [Enterprise docs](https://svgrid.com/docs) and [Pricing](https://svgrid.com/pricing).
+Full detail: [SvGrid vs AG Grid vs TanStack Table](https://svgrid.com/docs/help/comparison/) ·
+[Migrating from AG Grid](https://svgrid.com/docs/help/migrating-from-ag-grid/)
 
 ## Documentation
 
-- [Getting started](https://svgrid.com/docs) - end-to-end walkthrough.
-- [280+ live demos](https://svgrid.com/demos) - copy-paste recipes for every feature.
-- [Why headless?](https://svgrid.com/docs) - when to compose vs. drop in.
-- [Theming](https://svgrid.com/docs) - re-skin via `--sg-*` tokens and dark mode.
+- [Getting started](https://svgrid.com/docs/getting-started/) - end-to-end walkthrough.
+- [370+ live demos](https://svgrid.com/demos/) - copy-paste recipes for every feature.
+- [Why headless?](https://svgrid.com/docs/why-headless/) - when to compose vs. drop in.
+- [Theming and Tailwind](https://svgrid.com/docs/help/tailwind/) - re-skin via `--sg-*` tokens and dark mode.
+- [Accessibility](https://svgrid.com/docs/help/accessibility/) - the WAI-ARIA grid pattern as implemented.
+- [Bundle size](https://svgrid.com/docs/reference/bundle-size/) - measured numbers and how to reproduce them.
 
 ## Who's behind it
 
-SvGrid is built by [jQWidgets](https://www.jqwidgets.com), shipping UI components since 2011 to 5,000+ companies including Samsung, Boeing, NVIDIA, Microsoft, Nokia, and Intel. SvGrid is our Svelte 5 native effort.
+SvGrid is built by [jQWidgets](https://www.jqwidgets.com), shipping UI components since 2011 to 5,000+
+companies including Samsung, Boeing, NVIDIA, Microsoft, Nokia, and Intel. SvGrid is our Svelte 5 native
+effort.
 
 ## License & trademark
 
-The source code is **MIT-licensed** - see [LICENSE](./LICENSE). It is free for commercial use. SvGrid&trade; and sv-grid&trade; are trademarks of jQWidgets Ltd; the license covers the code only, not the name or logo.
+The source code is **MIT-licensed** - see [LICENSE](./LICENSE). It is free for commercial use.
+SvGrid&trade; and sv-grid&trade; are trademarks of jQWidgets Ltd; the license covers the code only, not
+the name or logo.

package/dist/GridMenus.svelte

@@ -39,6 +39,7 @@
     type TableFeatures,
   } from "./index";
   import "./sv-grid-scrollbar";
+  import { onScrollOutside } from "./a11y/dismissable";
   import type { Snippet } from "svelte";
   import { getKeyboardIntent, getNextActiveCell } from "./keyboard";
   import {
@@ -145,15 +146,20 @@
 
   // Column/filter/operator menus are position:fixed and anchored to their
   // trigger by a one-time measurement taken when they open. On scroll they'd
-  // otherwise detach and float over the wrong place (#88), so close them on any
-  // scroll (capture phase, to catch inner scroll containers) or resize.
+  // otherwise detach and float over the wrong place (#88), so close them when
+  // anything OUTSIDE them scrolls, or on resize. Scrolling the menu's own body
+  // or its facet list has to keep it open - hence onScrollOutside rather than a
+  // bare capture-phase listener.
   $effect(() => {
     if (!(columnMenuFor || filterMenuFor || operatorMenuFor || chooseColumnsPos)) return;
     const close = () => closeMenus();
-    window.addEventListener('scroll', close, true);
+    const offScroll = onScrollOutside(
+      () => Array.from(document.querySelectorAll<HTMLElement>('.sv-grid-menu')),
+      close,
+    );
     window.addEventListener('resize', close);
     return () => {
-      window.removeEventListener('scroll', close, true);
+      offScroll();
       window.removeEventListener('resize', close);
     };
   });

package/dist/SvColorInput.svelte

@@ -107,7 +107,7 @@
 <SvField frame id={uid} {label} {hint} {error} {required} {dir} {size} {invalid} {disabled} {readonly} {loading} {block} width={block ? undefined : 'fit-content'}>
   <button
     bind:this={triggerEl}
-    class="sv-color__trigger"
+    class="sv-color sv-color__trigger"
     class:is-disabled={disabled}
     {...col.swatchProps()}
     use:focusOpen

package/dist/SvContextMenu.svelte

@@ -17,7 +17,7 @@
    */
   import type { Snippet } from 'svelte'
   import { portalToBody, popIn } from './popover'
-  import { createDismissableLayer } from './a11y/dismissable'
+  import { createDismissableLayer, onScrollOutside } from './a11y/dismissable'
   import { createFocusTrap } from './a11y/focus-trap'
   import SvMenuList, { type MenuItem } from './SvMenuList.svelte'
 
@@ -76,9 +76,9 @@
     })
     layer.activate()
     // Reposition-close on scroll (a moved anchor would leave the menu stranded).
-    const onScroll = () => (open = false)
-    window.addEventListener('scroll', onScroll, true)
-    return () => { layer.release(); trap.release(); window.removeEventListener('scroll', onScroll, true) }
+    // Scrolling the menu's own item list doesn't count as the anchor moving.
+    const offScroll = onScrollOutside(() => panelEl, () => (open = false))
+    return () => { layer.release(); trap.release(); offScroll() }
   })
 </script>
 

package/dist/SvDrawer.svelte

@@ -99,6 +99,10 @@
       leaving = true
       leaveTimer = setTimeout(() => { show = false; leaving = false; onClosed?.() }, reduceMotion ? 0 : EXIT_MS)
     }
+    // `open` is this effect's only dependency, so the cleanup runs on reopen (a
+    // no-op after the clearTimeout above) or on destroy - where it matters, so a
+    // drawer unmounted mid-exit doesn't leave a timer firing into a dead scope.
+    return () => clearTimeout(leaveTimer)
   })
 
   // Swipe-down-to-close for the sheet grab handle.

package/dist/SvGrid.css

@@ -1780,6 +1780,9 @@ select.sv-grid-fr-editor {
   z-index: 901;
   max-height: calc(100vh - 24px);
   overflow: auto;
+  /* Keep a wheel that reaches the end of the menu from scrolling the grid
+     underneath it - that scroll would close the menu out from under the user. */
+  overscroll-behavior: contain;
   padding: 4px;
   background: var(--sg-bg, #fff);
   border: 1px solid var(--sg-border, #d6dee9);
@@ -2062,6 +2065,7 @@ select.sv-grid-fr-editor {
 .sv-grid-facet-list {
   max-height: 200px;
   overflow: auto;
+  overscroll-behavior: contain;
   border: 1px solid var(--sg-border, #eaeef4);
   border-radius: 5px;
 }

package/dist/SvPhoneInput.svelte

@@ -105,7 +105,9 @@
   {width}
   leading={countryChip}
 >
-  <input class="sv-phone__number" {...ph.inputProps()} />
+  <!-- `sv-phone` on the control is the component's public CSS/query hook, the
+       same convention SvCountryInput and the rest of the suite follow. -->
+  <input class="sv-phone sv-phone__number" {...ph.inputProps()} />
   {#if name}<input type="hidden" {name} value={ph.value} />{/if}
 </SvField>
 

package/dist/a11y/dismissable.d.ts

@@ -29,4 +29,15 @@ export type DismissableLayer = {
 export declare function createDismissableLayer(options: DismissableOptions): DismissableLayer;
 /** Test/introspection helper: current number of active layers. */
 export declare function dismissableDepth(): number;
+/**
+ * Close-on-scroll for popovers that are position:fixed and anchored by a
+ * one-time measurement taken when they open. Scrolling an ancestor slides the
+ * anchor out from under them, so they have to close - but scrolling INSIDE
+ * them (a long menu, a facet list) must not, which is what a bare capture-phase
+ * window listener gets wrong: inner scroll containers don't bubble, so the
+ * capture listener sees them and dismisses the panel the user is scrolling.
+ *
+ * Returns the unsubscribe function.
+ */
+export declare function onScrollOutside(element: () => DismissTarget, onOutside: () => void): () => void;
 export {};

package/dist/a11y/dismissable.js

@@ -52,3 +52,24 @@ export function createDismissableLayer(options) {
 export function dismissableDepth() {
     return stack.length;
 }
+/**
+ * Close-on-scroll for popovers that are position:fixed and anchored by a
+ * one-time measurement taken when they open. Scrolling an ancestor slides the
+ * anchor out from under them, so they have to close - but scrolling INSIDE
+ * them (a long menu, a facet list) must not, which is what a bare capture-phase
+ * window listener gets wrong: inner scroll containers don't bubble, so the
+ * capture listener sees them and dismisses the panel the user is scrolling.
+ *
+ * Returns the unsubscribe function.
+ */
+export function onScrollOutside(element, onOutside) {
+    if (typeof window === 'undefined')
+        return () => { };
+    const handler = (event) => {
+        if (containsTarget(element(), event.target))
+            return;
+        onOutside();
+    };
+    window.addEventListener('scroll', handler, true);
+    return () => window.removeEventListener('scroll', handler, true);
+}

package/dist/ai.js

@@ -42,14 +42,14 @@ export function hasAIProvider() {
 }
 class NoProviderError extends Error {
     constructor() {
-        super('@svgrid/enterprise/ai: no AI provider registered. Call setAIProvider(fn) ' +
+        super('@svgrid/grid ai: no AI provider registered. Call setAIProvider(fn) ' +
             'with an adapter that talks to OpenAI / Anthropic / your proxy.');
         this.name = 'NoProviderError';
     }
 }
 class BadJsonError extends Error {
     constructor(raw) {
-        super('@svgrid/enterprise/ai: provider returned non-JSON for a json-format request. ' +
+        super('@svgrid/grid ai: provider returned non-JSON for a json-format request. ' +
             `First 200 chars: ${raw.slice(0, 200)}`);
         this.name = 'BadJsonError';
     }
@@ -183,7 +183,7 @@ export async function aiFilter(api, query, opts = {}) {
  */
 export async function aiSmartFill(api, opts) {
     if (opts.examples.length === 0) {
-        throw new Error('@svgrid/enterprise/ai: aiSmartFill requires at least one example.');
+        throw new Error('@svgrid/grid ai: aiSmartFill requires at least one example.');
     }
     const data = api.getData();
     const targets = opts.targetRowIndices ??