@svgrid/grid 3.0.1 → 3.0.2

package/src/grid-icons.test.ts

@@ -0,0 +1,46 @@
+/**
+ * The icon catalogue as data: the name list and the glyph table have to agree
+ * with each other and with the filter-operator catalogue.
+ *
+ * The third test here is the one that earns its keep. Operator icons are
+ * data-driven (`filterOperatorOptions[].iconName`), and an operator naming an
+ * icon the grid has no case for renders an empty box rather than failing -
+ * which is exactly how `op-between` shipped blank. `GridIconName` makes that a
+ * compile error now, and this makes it a test failure too, so it also catches
+ * an operator added through a path that skips type-checking.
+ */
+import { describe, expect, it } from 'vitest'
+import { GRID_ICON_GLYPHS, GRID_ICON_NAMES, type GridIconName } from './grid-icons'
+import { filterOperatorOptions } from './filter-operators'
+
+describe('grid icon catalogue', () => {
+  it('lists every name exactly once', () => {
+    const dupes = GRID_ICON_NAMES.filter((n, i) => GRID_ICON_NAMES.indexOf(n) !== i)
+    expect(dupes, `duplicated icon names: ${dupes.join(', ')}`).toEqual([])
+  })
+
+  it('only maps glyphs for names in the catalogue', () => {
+    const orphans = Object.keys(GRID_ICON_GLYPHS).filter(
+      (k) => !GRID_ICON_NAMES.includes(k as GridIconName),
+    )
+    expect(orphans, `glyphs for unknown icons: ${orphans.join(', ')}`).toEqual([])
+  })
+
+  it('has a name for every filter operator icon', () => {
+    const missing = filterOperatorOptions
+      .map((o) => o.iconName)
+      .filter((n) => !GRID_ICON_NAMES.includes(n))
+    expect(missing, `operators naming an icon the grid cannot draw: ${missing.join(', ')}`).toEqual(
+      [],
+    )
+  })
+
+  it('keeps the pin icons separate from the operator icons they look like', () => {
+    // Pin used to render `op-startsWith` / `op-greaterThan` / `x` directly, so
+    // overriding a filter operator silently repainted the pin menu. Same
+    // default glyphs, different names.
+    for (const name of ['pin-left', 'pin-right', 'unpin'] as const) {
+      expect(GRID_ICON_NAMES).toContain(name)
+    }
+  })
+})

package/src/grid-icons.ts

@@ -0,0 +1,184 @@
+/**
+ * Grid chrome icons. Every glyph `<SvGrid>` draws for its own UI - sort
+ * indicators, the filter funnel, expanders, the pager arrows, tool-panel
+ * buttons - has a name here, and the `icons` prop replaces any subset of them.
+ *
+ * This mirrors `grid-messages.ts`: a name-keyed map with built-in defaults,
+ * where an unset name keeps the default. A partial map is all a consumer ever
+ * needs, so `icons` is safe to pass without knowing the full catalogue. That
+ * matters more than it looks - a single catch-all snippet would make the
+ * consumer responsible for every name the grid can ask for, and missing one
+ * renders an empty box. The `op-between` comment in SvGrid.svelte records what
+ * that looks like when it ships.
+ *
+ * Deliberately NOT in here:
+ *   - the scrollbar stepper arrows. `sv-grid-scrollbar.ts` is a custom element
+ *     that builds its SVG with `createElementNS` inside a shadow root, on
+ *     purpose, so it stays compatible with strict CSP / Trusted Types. A Svelte
+ *     snippet cannot render there. Theme it with the `--sg-scrollbar-*` tokens.
+ *   - the checkbox tick and its indeterminate dash. Both are `::after`
+ *     pseudo-elements drawn from borders (SvGrid.css), a form-control
+ *     affordance rather than an icon, and they render once per visible row.
+ *   - conditional formatting's `iconSet`. Those are value-driven data glyphs a
+ *     consumer already chooses; a different concept that shares the word.
+ */
+import type { Snippet } from 'svelte'
+
+/**
+ * Every icon `<SvGrid>` draws for its own chrome. Pass any subset of these to
+ * the `icons` prop to swap the built-in glyph for your own markup.
+ */
+export type GridIconName =
+  // ---- Header + column menu ----
+  | 'sort'
+  | 'sort-asc'
+  | 'sort-desc'
+  | 'filter'
+  | 'menu'
+  | 'group'
+  | 'x'
+  | 'chevron-down'
+  | 'chevron-right'
+  | 'autosize'
+  | 'columns'
+  | 'reset'
+  // ---- Filter operators (mirror `iconName` in filter-operators.ts) ----
+  | 'op-contains'
+  | 'op-notContains'
+  | 'op-equals'
+  | 'op-notEquals'
+  | 'op-startsWith'
+  | 'op-endsWith'
+  | 'op-regex'
+  | 'op-in'
+  | 'op-notIn'
+  | 'op-greaterThan'
+  | 'op-lessThan'
+  | 'op-between'
+  | 'op-isBlank'
+  | 'op-isNotBlank'
+  // ---- Pinning. Their defaults borrow the operator glyphs above, but they get
+  // their own names so overriding a filter operator does not silently repaint
+  // the pin menu. ----
+  | 'pin-left'
+  | 'pin-right'
+  | 'unpin'
+  // ---- Toolbar + overlays ----
+  | 'search'
+  | 'tool-panel'
+  | 'chart'
+  | 'advanced-filter'
+  | 'column-group-caret'
+  // ---- Glyph icons: the built-in is a character, not a path ----
+  | 'close'
+  | 'clear'
+  | 'remove'
+  | 'row-number'
+  | 'pinned-row-top'
+  | 'pinned-row-bottom'
+  | 'find-prev'
+  | 'find-next'
+  | 'move-up'
+  | 'move-down'
+  | 'group-add'
+  | 'page-first'
+  | 'page-prev'
+  | 'page-next'
+  | 'page-last'
+  | 'page-size-caret'
+  | 'drag-handle'
+  | 'breadcrumb-separator'
+
+/**
+ * Consumer icon overrides, keyed by name. Any subset; names you leave out keep
+ * their built-in glyph, so `icons` never has to be exhaustive.
+ */
+export type GridIcons = Partial<Record<GridIconName, Snippet>>
+
+/**
+ * Icons whose built-in form is a character rather than an SVG path. Kept as
+ * data so `<SvGrid>`, its footer and the standalone `SvRowGroupPanel` render
+ * the same defaults instead of three copies drifting apart.
+ *
+ * Each is the exact character that shipped inline before, so a grid that sets
+ * no `icons` renders byte-for-byte what it always did.
+ */
+export const GRID_ICON_GLYPHS: Partial<Record<GridIconName, string>> = {
+  close: '✕', // multiplication X
+  clear: '✕',
+  remove: '×', // multiplication sign
+  'row-number': '#',
+  'pinned-row-top': '↑', // upwards arrow
+  'pinned-row-bottom': '↓', // downwards arrow
+  'find-prev': '↑',
+  'find-next': '↓',
+  'move-up': '↑',
+  'move-down': '↓',
+  'group-add': '⊞', // squared plus
+  'page-first': '⇤', // leftwards arrow to bar
+  'page-prev': '‹', // single left-pointing angle quote
+  'page-next': '›', // single right-pointing angle quote
+  'page-last': '⇥', // rightwards arrow to bar
+  'page-size-caret': '▾', // black down-pointing small triangle
+  'drag-handle': '⠿', // braille pattern dots-123456, the grip
+  'breadcrumb-separator': '›',
+}
+
+/**
+ * Every icon name, in catalogue order. Exported for tests and docs generation;
+ * the grid itself never reads it, so it costs a consumer's bundle nothing.
+ */
+export const GRID_ICON_NAMES: ReadonlyArray<GridIconName> = [
+  'sort',
+  'sort-asc',
+  'sort-desc',
+  'filter',
+  'menu',
+  'group',
+  'x',
+  'chevron-down',
+  'chevron-right',
+  'autosize',
+  'columns',
+  'reset',
+  'op-contains',
+  'op-notContains',
+  'op-equals',
+  'op-notEquals',
+  'op-startsWith',
+  'op-endsWith',
+  'op-regex',
+  'op-in',
+  'op-notIn',
+  'op-greaterThan',
+  'op-lessThan',
+  'op-between',
+  'op-isBlank',
+  'op-isNotBlank',
+  'pin-left',
+  'pin-right',
+  'unpin',
+  'search',
+  'tool-panel',
+  'chart',
+  'advanced-filter',
+  'column-group-caret',
+  'close',
+  'clear',
+  'remove',
+  'row-number',
+  'pinned-row-top',
+  'pinned-row-bottom',
+  'find-prev',
+  'find-next',
+  'move-up',
+  'move-down',
+  'group-add',
+  'page-first',
+  'page-prev',
+  'page-next',
+  'page-last',
+  'page-size-caret',
+  'drag-handle',
+  'breadcrumb-separator',
+]

package/src/icon-overrides.grid.test.ts

@@ -0,0 +1,188 @@
+/**
+ * DOM: the `icons` prop replaces the grid's own glyphs, one name at a time.
+ *
+ * The contract these lock in:
+ *   - per-name fallback. Overriding one icon must not blank the others; that
+ *     cliff is the whole reason `icons` is a map and not a single snippet.
+ *   - an override reaches the lazily-imported column menu, not just the parts
+ *     of the grid that render eagerly.
+ *   - overriding a filter operator does NOT repaint the pin menu, which shared
+ *     its glyphs before this feature.
+ *   - defaults are untouched when `icons` is absent.
+ *
+ * jsdom does not compute `transform`, so the rotation contract is asserted as
+ * the class hook the CSS keys off (`.sv-grid-icon` on the wrapper, as a direct
+ * child of the toggle) rather than as a computed style. The rotation itself is
+ * browser-only verification.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createRawSnippet, flushSync, mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  createCoreRowModel,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  sortFns,
+  tableFeatures,
+  rowSortingFeature,
+} from './index'
+import type { ColumnDef } from './index'
+
+type Row = { id: number; name: string }
+const features = tableFeatures({ rowSortingFeature })
+const cols: ColumnDef<typeof features, Row>[] = [{ field: 'name', header: 'Name', width: 160 }]
+const data: Row[] = Array.from({ length: 12 }, (_, i) => ({ id: i, name: `n${i}` }))
+
+const tick = () => new Promise<void>((r) => queueMicrotask(r))
+
+/** A marker icon that is trivially findable in the DOM. */
+const mark = (id: string) =>
+  createRawSnippet(() => ({
+    render: () => `<svg data-icon="${id}"><path d="M0 0" /></svg>`,
+  }))
+
+function mountGrid(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvGrid, {
+    target,
+    props: {
+      data,
+      columns: cols,
+      features,
+      _rowModels: {
+        coreRowModel: createCoreRowModel(),
+        filteredRowModel: createFilteredRowModel(),
+        sortedRowModel: createSortedRowModel(sortFns),
+        paginatedRowModel: createPaginatedRowModel(),
+      },
+      containerHeight: 240,
+      virtualization: false,
+      ...props,
+    } as never,
+  })
+  return { target, app, destroy: () => { unmount(app); target.remove() } }
+}
+
+let cleanup: (() => void) | null = null
+afterEach(() => { cleanup?.(); cleanup = null })
+
+describe('icons prop', () => {
+  it('renders the built-in glyphs when no icons are passed', async () => {
+    const { target, destroy } = mountGrid({ showColumnMenu: true })
+    cleanup = destroy
+    await tick()
+    // The header menu button draws a real <svg> from the built-in catalogue.
+    const menuBtn = target.querySelector('.sv-grid-col-menu-btn')
+    expect(menuBtn).not.toBeNull()
+    expect(menuBtn!.querySelector('svg.sv-grid-icon')).not.toBeNull()
+    expect(target.querySelector('[data-icon]')).toBeNull()
+  })
+
+  it('replaces one icon and leaves the rest alone', async () => {
+    const { target, destroy } = mountGrid({
+      showColumnMenu: true,
+      showFilterRow: true,
+      icons: { menu: mark('m') },
+    })
+    cleanup = destroy
+    await tick()
+
+    const menuBtn = target.querySelector('.sv-grid-col-menu-btn')!
+    // The override is there...
+    expect(menuBtn.querySelector('[data-icon="m"]')).not.toBeNull()
+    // ...and the built-in it replaced is not drawn alongside it.
+    expect(menuBtn.querySelector('svg.sv-grid-icon')).toBeNull()
+    // An unset name still renders its built-in. This is the assertion that a
+    // single catch-all snippet could not satisfy.
+    expect(target.querySelectorAll('svg.sv-grid-icon').length).toBeGreaterThan(0)
+  })
+
+  it('wraps an override in the icon box the CSS keys off', async () => {
+    const { target, destroy } = mountGrid({ showColumnMenu: true, icons: { menu: mark('m') } })
+    cleanup = destroy
+    await tick()
+    const wrapper = target.querySelector('[data-icon="m"]')!.parentElement!
+    expect(wrapper.classList.contains('sv-grid-icon')).toBe(true)
+    expect(wrapper.classList.contains('sv-grid-icon-custom')).toBe(true)
+  })
+
+  it('reaches the lazily-imported column menu', async () => {
+    const { target, destroy } = mountGrid({
+      showColumnMenu: true,
+      icons: { 'sort-asc': mark('sa') },
+    })
+    cleanup = destroy
+    await tick()
+    ;(target.querySelector('.sv-grid-col-menu-btn') as HTMLElement).click()
+    // GridMenus arrives through a dynamic import(), so poll rather than
+    // guessing a tick count.
+    await vi.waitFor(() => {
+      expect(target.querySelector('[data-icon="sa"]')).not.toBeNull()
+    })
+  })
+
+  it('does not repaint the pin menu when a filter operator is overridden', async () => {
+    const { target, destroy } = mountGrid({
+      showColumnMenu: true,
+      // The pin section is hidden while columns are virtualized, and that
+      // defaults to on. This is COLUMN virtualization, not the row
+      // `virtualization: false` the shared helper sets.
+      columnVirtualization: false,
+      icons: { 'op-startsWith': mark('sw') },
+    })
+    cleanup = destroy
+    await tick()
+    ;(target.querySelector('.sv-grid-col-menu-btn') as HTMLElement).click()
+
+    // Assert the item is really there before asserting about its icon -
+    // a conditional check here would pass just as happily if the pin menu
+    // stopped rendering at all.
+    const pinLeft = await vi.waitFor(() => {
+      const el = [...target.querySelectorAll('.sv-grid-menu-item')].find((e) =>
+        e.textContent?.includes('Pin to left'),
+      )
+      expect(el).toBeTruthy()
+      return el!
+    })
+
+    // Pin borrowed `op-startsWith` before this feature; it must not follow
+    // that override now.
+    expect(pinLeft.querySelector('[data-icon="sw"]')).toBeNull()
+    expect(pinLeft.querySelector('svg.sv-grid-icon')).not.toBeNull()
+  })
+
+  it('overrides the pager arrows through GridFooter', async () => {
+    const { target, destroy } = mountGrid({
+      showPagination: true,
+      pageSize: 5,
+      icons: { 'page-next': mark('pn') },
+    })
+    cleanup = destroy
+    await tick()
+    const hit = target.querySelector('[data-icon="pn"]')
+    expect(hit).not.toBeNull()
+    // Still a real pager button, and its label is untouched: icons and
+    // localeText are independent axes.
+    const btn = hit!.closest('.sv-grid-pagination-btn')
+    expect(btn).not.toBeNull()
+    expect(btn!.getAttribute('aria-label')).toBe('Next page')
+  })
+
+  it('picks up icons set after mount through api.setOption', async () => {
+    let api: { setOption: (k: string, v: unknown) => void } | undefined
+    const { target, destroy } = mountGrid({
+      showColumnMenu: true,
+      onApiReady: (a: typeof api) => (api = a),
+    })
+    cleanup = destroy
+    await tick()
+    expect(target.querySelector('[data-icon="rt"]')).toBeNull()
+
+    api!.setOption('icons', { menu: mark('rt') })
+    flushSync()
+    await tick()
+    expect(target.querySelector('[data-icon="rt"]')).not.toBeNull()
+  })
+})

package/src/icon-seam.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Source scan: every chrome icon goes through the `icon` snippet.
+ *
+ * The `icons` prop is only worth having if it covers the chrome, and coverage
+ * is the kind of thing that rots one commit at a time - somebody adds a toolbar
+ * button with an inline `<svg>`, it works, nobody notices it ignores `icons`
+ * until a consumer reports a stray glyph in a re-skinned grid. This is the
+ * check that turns that into a red test instead.
+ *
+ * It reads source rather than DOM on purpose: a rendering test can only cover
+ * the states it happens to mount, and the icons most likely to be missed are
+ * the ones behind a rarely-exercised branch.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { GRID_ICON_GLYPHS, GRID_ICON_NAMES, type GridIconName } from './grid-icons'
+
+const SRC = join(process.cwd(), 'src')
+const read = (f: string) => readFileSync(join(SRC, f), 'utf8')
+
+/** Files that render grid chrome and therefore must go through the seam. */
+const CHROME = ['SvGrid.svelte', 'GridMenus.svelte', 'GridFooter.svelte', 'SvRowGroupPanel.svelte']
+
+/**
+ * Drop the regions allowed to contain raw icon markup: the `icon` snippet's own
+ * body (which IS the built-in set), the `ic` snippet in SvRowGroupPanel, and
+ * every `<script>` block.
+ */
+function stripAllowedRegions(src: string): string {
+  let out = src.replace(/<script[\s\S]*?<\/script>/g, '')
+  // The built-in catalogue: from the snippet header to its closing tag.
+  out = out.replace(/\{#snippet icon\(name: GridIconName\)\}[\s\S]*?\n\{\/snippet\}/g, '')
+  out = out.replace(/\{#snippet ic\(name: GridIconName\)\}[\s\S]*?\{\/snippet\}/g, '')
+  return out
+}
+
+describe('icon seam', () => {
+  it('leaves no inline <svg> outside the built-in catalogue', () => {
+    // Data visualisation is not chrome: these draw values, not affordances, and
+    // there is nothing for a consumer's icon set to say about them.
+    const ALLOWED = ['sv-grid-sparkline']
+
+    const offenders: string[] = []
+    for (const file of CHROME) {
+      const body = stripAllowedRegions(read(file))
+      for (const [i, line] of body.split('\n').entries()) {
+        if (!line.includes('<svg')) continue
+        if (ALLOWED.some((a) => body.split('\n').slice(i, i + 3).join(' ').includes(a))) continue
+        offenders.push(`${file}:${i + 1} ${line.trim().slice(0, 80)}`)
+      }
+    }
+    expect(
+      offenders,
+      `Inline <svg> outside the icon snippet - route it through {@render icon("...")} ` +
+        `and add a name to grid-icons.ts:\n  ${offenders.join('\n  ')}`,
+    ).toEqual([])
+  })
+
+  it('leaves no glyph character used as an icon', () => {
+    // Every character the catalogue owns. If one of these appears as an
+    // element's text content outside the snippet, it is an icon that bypassed
+    // the seam.
+    const glyphs = [...new Set(Object.values(GRID_ICON_GLYPHS))].filter((g) => g !== '#')
+    const offenders: string[] = []
+    for (const file of CHROME) {
+      const body = stripAllowedRegions(read(file))
+      for (const [i, line] of body.split('\n').entries()) {
+        for (const g of glyphs) {
+          // `>GLYPH<` is the shape of a glyph rendered as element content.
+          if (new RegExp(`>\\s*${escapeRe(g)}\\s*<`).test(line)) {
+            offenders.push(`${file}:${i + 1} ${JSON.stringify(g)} in ${line.trim().slice(0, 70)}`)
+          }
+        }
+      }
+    }
+    expect(
+      offenders,
+      `Glyph rendered directly instead of through the icon seam:\n  ${offenders.join('\n  ')}`,
+    ).toEqual([])
+  })
+
+  it('only renders names the catalogue defines', () => {
+    const unknown: string[] = []
+    for (const file of CHROME) {
+      const src = read(file)
+      for (const m of src.matchAll(/\{@render ic(?:on)?\(\s*["']([a-zA-Z-]+)["']\s*\)\}/g)) {
+        const name = m[1] as GridIconName
+        if (!GRID_ICON_NAMES.includes(name)) unknown.push(`${file}: ${name}`)
+      }
+    }
+    expect(unknown, `Icon names with no entry in grid-icons.ts:\n  ${unknown.join('\n  ')}`).toEqual(
+      [],
+    )
+  })
+})
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/src/index.ts

@@ -536,6 +536,12 @@ export {
   buildChart,
   formatChartValue,
   rowsToChartSpec,
+  rowsToBoxSpec,
+  rowsToDirectSpec,
+  boxStats,
+  sliceChartWindow,
+  chartScales,
+  ordinalDateTicks,
   niceScale,
   niceLogScale,
   linearTrend,
@@ -550,7 +556,13 @@ export {
   type ChartSpec,
   type ChartSeries,
   type ChartGeometry,
+  type ChartScales,
   type ChartBar,
+  type ChartCandle,
+  type ChartBox,
+  type ChartErrorBar,
+  type BoxStats,
+  type OhlcBar,
   type ChartLine,
   type ChartLinePoint,
   type ChartPieSlice,
@@ -581,6 +593,7 @@ export {
   downloadChartSvg,
   chartToPngBlob,
   downloadChartPng,
+  chartCsvExportable,
   chartSpecToCsv,
   downloadChartCsv,
   type ChartExportOptions,
@@ -693,6 +706,12 @@ export {
   resolveGridMessages,
   type GridMessages,
 } from './grid-messages'
+export {
+  GRID_ICON_GLYPHS,
+  GRID_ICON_NAMES,
+  type GridIconName,
+  type GridIcons,
+} from './grid-icons'
 export {
   insertGroupFooters,
   buildAutoGroupColumns,