@svgrid/enterprise 2.0.4 → 2.2.0

package/src/install.ts

@@ -12,6 +12,8 @@ import { isLicenseKeySet } from './license'
 import { emitUnlicensedNudge } from './watermark'
 import {
   aiFilter, aiSmartFill, aiSummarize, aiClassify, aiExport, aiFindAnomalies,
+  aiChart, enableAiCharting,
+  type AIChartOptions, type AIChartPlan,
   type AIFilterOptions, type AIFilterResult,
   type AISmartFillOptions, type AISmartFillResult,
   type AISummarizeOptions, type AISummary,
@@ -24,6 +26,7 @@ import {
   type PivotConfig,
   type PivotResult,
 } from './pivot'
+import { enableSchedulerView } from './scheduler'
 
 export type EnterpriseAIApi<TData extends RowData> = {
   /** Natural-language -> filter + sort plan (and optionally apply it). */
@@ -38,6 +41,8 @@ export type EnterpriseAIApi<TData extends RowData> = {
   export(query: string, opts?: AIExportOptions): Promise<AIExportPlan>
   /** Scan a slice for anomalies / outliers, returning a structured list. */
   findAnomalies(opts?: AIAnomalyOptions): Promise<AIAnomalyResult>
+  /** Natural-language chart: "revenue by region, stacked by product". */
+  chart(query: string, opts?: AIChartOptions): Promise<AIChartPlan>
   // TData is referenced so the type stays bound to the row shape even
   // though the helpers all read through `api.getData()`. Lets callers
   // get correct inference downstream without explicit generics.
@@ -117,7 +122,12 @@ export function installEnterprise<
     classify: (opts) => aiClassify(pro, opts),
     export: (query, opts) => aiExport(pro, query, opts),
     findAnomalies: (opts) => aiFindAnomalies(pro, opts),
+    chart: (query, opts) => aiChart(pro, query, opts),
   }
+  // Wire the built-in chart panel's AI button (no-op without the `charting` prop).
+  enableAiCharting(pro)
+  // Register the scheduler / calendar view (no-op without the `scheduler` prop).
+  enableSchedulerView()
   pro.pivot = {
     build: (config) =>
       createPivotModel<TFeatures, TData>(pro.getData(), config),

package/src/pivot-chart.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+import { createPivotModel } from './pivot'
+import { pivotToChartSpec } from './pivot-chart'
+
+const data = [
+  { region: 'EMEA', product: 'A', revenue: 100 },
+  { region: 'EMEA', product: 'B', revenue: 200 },
+  { region: 'APAC', product: 'A', revenue: 50 },
+  { region: 'APAC', product: 'B', revenue: 70 },
+]
+
+describe('pivotToChartSpec', () => {
+  it('maps row leaves to categories and column leaves to series', () => {
+    const result = createPivotModel(data, {
+      rows: ['region'],
+      cols: ['product'],
+      values: [{ field: 'revenue', agg: 'sum' }],
+      grandTotalRow: false,
+      grandTotalCol: false,
+    })
+    const spec = pivotToChartSpec(result, { type: 'bar' })
+    expect(spec.type).toBe('bar')
+    expect([...spec.categories].sort()).toEqual(['APAC', 'EMEA'])
+    // One series per product.
+    expect(spec.series.map((s) => s.label).sort()).toEqual(['A', 'B'])
+    const emeaIdx = spec.categories.indexOf('EMEA')
+    expect(spec.series.find((s) => s.label === 'A')!.values[emeaIdx]).toBe(100)
+    expect(spec.series.find((s) => s.label === 'B')!.values[emeaIdx]).toBe(200)
+  })
+
+  it('excludes the grand-total column / row and stacks when asked', () => {
+    const result = createPivotModel(data, {
+      rows: ['region'],
+      cols: ['product'],
+      values: [{ field: 'revenue', agg: 'sum' }],
+      grandTotalRow: true,
+      grandTotalCol: true,
+    })
+    const spec = pivotToChartSpec(result, { stacked: true })
+    expect(spec.series.some((s) => /total/i.test(s.label))).toBe(false)
+    expect(spec.categories.some((c) => /total/i.test(c))).toBe(false)
+    expect(spec.stacked).toBe(true)
+  })
+
+  it('labels nested row leaves by their full path', () => {
+    const nested = [
+      { region: 'EMEA', country: 'UK', revenue: 10 },
+      { region: 'EMEA', country: 'France', revenue: 20 },
+      { region: 'APAC', country: 'Japan', revenue: 30 },
+    ]
+    const result = createPivotModel(nested, {
+      rows: ['region', 'country'],
+      cols: [],
+      values: [{ field: 'revenue', agg: 'sum', label: 'Revenue' }],
+      grandTotalRow: false,
+      grandTotalCol: false,
+      rowSubtotals: false,
+    })
+    const spec = pivotToChartSpec(result)
+    // Leaf categories are the own labels...
+    expect(spec.categories).toContain('UK')
+    expect(spec.categories).toContain('France')
+    expect(spec.categories).toContain('Japan')
+    // ...and a parent group tier spans them.
+    expect(spec.categoryGroups).toBeTruthy()
+    const spans = spec.categoryGroups!.reduce((a, g) => a + g.span, 0)
+    expect(spans).toBe(spec.categories.length)
+    expect(spec.categoryGroups!.map((g) => g.label).sort()).toEqual(['APAC', 'EMEA'])
+    expect(spec.categoryGroups!.find((g) => g.label === 'EMEA')!.span).toBe(2)
+  })
+
+  it('handles no column dims (one series per measure)', () => {
+    const result = createPivotModel(data, {
+      rows: ['region'],
+      cols: [],
+      values: [{ field: 'revenue', agg: 'sum', label: 'Revenue' }],
+      grandTotalRow: false,
+      grandTotalCol: false,
+    })
+    const spec = pivotToChartSpec(result)
+    expect(spec.series.length).toBe(1)
+    expect(spec.series[0]!.label).toBe('Revenue')
+    const emeaIdx = spec.categories.indexOf('EMEA')
+    expect(spec.series[0]!.values[emeaIdx]).toBe(300)
+  })
+})

package/src/pivot-chart.ts

@@ -0,0 +1,112 @@
+/**
+ * Pivot -> chart bridge.
+ *
+ * Turns a computed {@link PivotResult} (the row/column/value matrix the pivot
+ * engine produces) into a core {@link ChartSpec} the free `SvGridChart` can
+ * render - so one pivot layout drives both a table and a chart (the Excel
+ * PivotTable <-> PivotChart pairing).
+ *
+ * Mapping:
+ *   - categories = the row-axis LEAF rows (deepest grouping; subtotals and the
+ *     grand-total row are skipped). With no row dims, the single total row.
+ *   - series     = the column-axis leaf value columns (one per col-path x
+ *     measure). The grand-total column is excluded unless `includeTotals`.
+ *   - values     = each leaf row's aggregated cell for that series column.
+ */
+import type { ChartSpec, ChartType, TableFeatures } from '@svgrid/grid'
+import type { PivotResult } from './pivot'
+
+export type PivotChartOptions = {
+  /** Chart type. Default `'bar'`. */
+  type?: ChartType
+  /** Stack the series. Default false. */
+  stacked?: boolean
+  /** Include the grand-total column / row as a series / category. Default false. */
+  includeTotals?: boolean
+  /** Cap the number of categories (row leaves) charted. */
+  maxCategories?: number
+}
+
+type LooseColumn = {
+  id?: string
+  header?: unknown
+  columns?: LooseColumn[]
+}
+
+export function pivotToChartSpec<TFeatures extends TableFeatures>(
+  result: PivotResult<TFeatures>,
+  opts: PivotChartOptions = {},
+): ChartSpec {
+  const type: ChartType = opts.type ?? 'bar'
+
+  // Category rows: the row-axis leaves. Fall back to the grand-total (single
+  // "All") row when no row dims are configured, then to every row.
+  let catRows = result.rows.filter((r) => r.__pivotKind === 'leaf')
+  if (!catRows.length) catRows = result.rows.filter((r) => r.__pivotKind === 'grandTotal')
+  if (!catRows.length) catRows = result.rows.slice()
+  if (opts.maxCategories && catRows.length > opts.maxCategories) {
+    catRows = catRows.slice(0, opts.maxCategories)
+  }
+  // Categories are the leaf's OWN label; when rows are nested, emit a parent
+  // tier (categoryGroups) so the axis reads "Americas | Canada · USA ..." as a
+  // grouped axis rather than colliding on a bare repeated leaf label.
+  const byId = new Map(result.rows.map((r) => [r.__pivotId, r]))
+  const ownLabel = (r: (typeof result.rows)[number]) => String(r.__pivotLabel ?? '').trim() || '(blank)'
+  const categories = catRows.map(ownLabel)
+
+  const parentOf = (r: (typeof result.rows)[number]) =>
+    r.__pivotParentId ? byId.get(r.__pivotParentId) : undefined
+  const nested = catRows.length > 0 && catRows.every((r) => parentOf(r) !== undefined)
+  let categoryGroups: Array<{ label: string; span: number }> | undefined
+  if (nested) {
+    categoryGroups = []
+    let prevId: string | null | undefined
+    for (const r of catRows) {
+      const pid = r.__pivotParentId
+      const last = categoryGroups[categoryGroups.length - 1]
+      if (last && pid === prevId) last.span += 1
+      else {
+        categoryGroups.push({ label: ownLabel(parentOf(r)!), span: 1 })
+        prevId = pid
+      }
+    }
+  }
+
+  // Collect the leaf value columns, carrying the accumulated column-group path
+  // so a series can be labelled by its column path (e.g. "Q1", "Q1 · Revenue").
+  type Leaf = { id: string; path: string[]; header: string }
+  const leaves: Leaf[] = []
+  const walk = (cols: LooseColumn[] | undefined, path: string[]): void => {
+    for (const c of cols ?? []) {
+      if (!c || c.id === '__pivotRowHeader') continue
+      // Skip the grand-total column group (and its leaves) unless asked for.
+      if (!opts.includeTotals && typeof c.id === 'string' && c.id.startsWith('pv_group__grand')) continue
+      if (Array.isArray(c.columns)) walk(c.columns, [...path, String(c.header ?? '')])
+      else if (typeof c.id === 'string') leaves.push({ id: c.id, path, header: String(c.header ?? '') })
+    }
+  }
+  walk(result.columns as unknown as LooseColumn[], [])
+
+  const filtered = opts.includeTotals ? leaves : leaves.filter((l) => !l.id.includes('__total'))
+  const uniqueHeaders = new Set(filtered.map((l) => l.header))
+  const series = filtered.map((l) => ({
+    label:
+      l.path.length === 0
+        ? l.header
+        : uniqueHeaders.size > 1
+          ? [...l.path, l.header].join(' · ')
+          : l.path.join(' · '),
+    values: catRows.map((r) => {
+      const v = r[l.id]
+      return typeof v === 'number' ? v : Number(v) || 0
+    }),
+  }))
+
+  return {
+    type,
+    categories,
+    series,
+    ...(categoryGroups && categoryGroups.length > 1 ? { categoryGroups } : {}),
+    ...(opts.stacked ? { stacked: true } : {}),
+  }
+}

package/src/scheduler.ts

@@ -0,0 +1,37 @@
+/**
+ * scheduler (view) - registers the Enterprise calendar / scheduler renderer with
+ * the grid so `<SvGrid scheduler={...}>` renders a full Month / Week / Day /
+ * Agenda calendar instead of the table. The grid ships the `scheduler` prop and
+ * its config types for free; the *renderer* (SvGridScheduler) is Pro and plugs
+ * in through the grid's `registerSchedulerView` seam.
+ *
+ * Soft-gated like the rest of Enterprise: it works without a license key but the
+ * grid shows the "unlicensed" watermark + a one-time console nudge.
+ *
+ * ```ts
+ * import { setLicenseKey, enableSchedulerView } from '@svgrid/enterprise'
+ * setLicenseKey('YOUR-KEY')
+ * enableSchedulerView()
+ * // then: <SvGrid {data} {columns} scheduler={{ startField: 'start', endField: 'end' }} />
+ * ```
+ */
+import { registerSchedulerView } from '@svgrid/grid'
+import { isLicenseKeySet } from './license'
+import { emitUnlicensedNudge } from './watermark'
+import SvGridScheduler from './SvGridScheduler.svelte'
+
+let enabled = false
+
+/**
+ * Register the Enterprise scheduler view. Idempotent - safe to call from every
+ * component that uses `scheduler`, or once at app start. Also invoked by
+ * {@link installEnterprise} so wiring the Pro API turns the view on too.
+ */
+export function enableSchedulerView(): void {
+  if (enabled) return
+  enabled = true
+  registerSchedulerView(SvGridScheduler as never)
+  if (!isLicenseKeySet()) emitUnlicensedNudge()
+}
+
+export { default as SvGridScheduler } from './SvGridScheduler.svelte'

package/src/scheduling.test.ts

@@ -0,0 +1,194 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  parseCron,
+  cronMatches,
+  isScheduleDue,
+  nextRun,
+  createScheduler,
+  CRON_PRESETS,
+  type Schedule,
+} from './scheduling'
+
+// A fixed reference instant: Monday 2026-07-27, 17:30 local time.
+// (2026-07-27 is a Monday; getDay() === 1.)
+const MON_1730 = new Date(2026, 6, 27, 17, 30, 0)
+
+describe('parseCron', () => {
+  it('rejects the wrong field count', () => {
+    expect(() => parseCron('* * * *')).toThrow(/5 fields/)
+    expect(() => parseCron('0 9 * * * *')).toThrow(/5 fields/)
+  })
+
+  it('rejects an unparseable step', () => {
+    expect(() => parseCron('*/0 * * * *')).toThrow(/step/)
+  })
+})
+
+describe('cronMatches', () => {
+  it('matches an exact minute/hour', () => {
+    expect(cronMatches('30 17 * * *', MON_1730)).toBe(true)
+    expect(cronMatches('31 17 * * *', MON_1730)).toBe(false)
+    expect(cronMatches('30 16 * * *', MON_1730)).toBe(false)
+  })
+
+  it('matches weekday ranges (1-5 = Mon-Fri)', () => {
+    expect(cronMatches('30 17 * * 1-5', MON_1730)).toBe(true)
+    const sun = new Date(2026, 6, 26, 17, 30) // Sunday
+    expect(cronMatches('30 17 * * 1-5', sun)).toBe(false)
+  })
+
+  it('accepts 7 as an alias for Sunday', () => {
+    const sun = new Date(2026, 6, 26, 9, 0)
+    expect(cronMatches('0 9 * * 7', sun)).toBe(true)
+    expect(cronMatches('0 9 * * 0', sun)).toBe(true)
+  })
+
+  it('honors step values (*/15)', () => {
+    expect(cronMatches('*/15 * * * *', new Date(2026, 6, 27, 10, 0))).toBe(true)
+    expect(cronMatches('*/15 * * * *', new Date(2026, 6, 27, 10, 15))).toBe(true)
+    expect(cronMatches('*/15 * * * *', new Date(2026, 6, 27, 10, 7))).toBe(false)
+  })
+
+  it('honors lists (0,30)', () => {
+    expect(cronMatches('0,30 * * * *', new Date(2026, 6, 27, 10, 0))).toBe(true)
+    expect(cronMatches('0,30 * * * *', new Date(2026, 6, 27, 10, 30))).toBe(true)
+    expect(cronMatches('0,30 * * * *', new Date(2026, 6, 27, 10, 15))).toBe(false)
+  })
+
+  it('uses UNION semantics when both day-of-month and day-of-week are set', () => {
+    // Fires on the 1st OR on any Monday. 2026-07-27 is a Monday (not the 1st).
+    expect(cronMatches('0 9 1 * 1', new Date(2026, 6, 27, 9, 0))).toBe(true)
+    // 2026-07-15 is a Wednesday and not the 1st -> neither matches.
+    expect(cronMatches('0 9 1 * 1', new Date(2026, 6, 15, 9, 0))).toBe(false)
+    // The 1st of the month, a Wednesday -> dom matches.
+    expect(cronMatches('0 9 1 * 1', new Date(2026, 6, 1, 9, 0))).toBe(true)
+  })
+
+  it('every preset parses and matches at least one time this year', () => {
+    for (const p of CRON_PRESETS) {
+      expect(() => parseCron(p.cron)).not.toThrow()
+      expect(nextRun({ id: p.label, cron: p.cron }, MON_1730)).toBeInstanceOf(Date)
+    }
+  })
+})
+
+describe('isScheduleDue', () => {
+  it('is false when disabled', () => {
+    expect(isScheduleDue({ id: 'a', cron: '30 17 * * *', enabled: false }, MON_1730)).toBe(false)
+  })
+
+  it('fires a one-off in its exact minute only', () => {
+    const s: Schedule = { id: 'once', runAt: MON_1730.toISOString() }
+    expect(isScheduleDue(s, MON_1730)).toBe(true)
+    expect(isScheduleDue(s, new Date(2026, 6, 27, 17, 31))).toBe(false)
+  })
+
+  it('prefers runAt over cron when both are present', () => {
+    const s: Schedule = { id: 'both', runAt: MON_1730.toISOString(), cron: '0 0 * * *' }
+    expect(isScheduleDue(s, MON_1730)).toBe(true)
+    expect(isScheduleDue(s, new Date(2026, 6, 27, 0, 0))).toBe(false)
+  })
+})
+
+describe('nextRun', () => {
+  it('finds the next cron occurrence', () => {
+    const from = new Date(2026, 6, 27, 17, 31) // just after 17:30
+    const next = nextRun({ id: 'eod', cron: '30 17 * * 1-5' }, from)
+    // Next weekday 17:30 is Tuesday the 28th.
+    expect(next).toEqual(new Date(2026, 6, 28, 17, 30))
+  })
+
+  it('returns null for a one-off already in the past', () => {
+    const past = new Date(2020, 0, 1, 0, 0).toISOString()
+    expect(nextRun({ id: 'old', runAt: past }, MON_1730)).toBeNull()
+  })
+
+  it('returns the one-off instant when still in the future', () => {
+    const future = new Date(2026, 6, 27, 18, 0)
+    expect(nextRun({ id: 'soon', runAt: future.toISOString() }, MON_1730)).toEqual(future)
+  })
+})
+
+describe('createScheduler', () => {
+  it('fires a due schedule exactly once per minute across repeated ticks', () => {
+    const onFire = vi.fn()
+    let clock = MON_1730
+    const scheduler = createScheduler({
+      schedules: [{ id: 'eod', cron: '30 17 * * 1-5' }],
+      onFire,
+      now: () => clock,
+    })
+    // Two ticks in the same minute (the 30s interval fires twice a minute).
+    scheduler.tick()
+    scheduler.tick()
+    expect(onFire).toHaveBeenCalledTimes(1)
+    expect(onFire).toHaveBeenCalledWith(expect.objectContaining({ id: 'eod' }), clock)
+
+    // Advance a minute past the match: no new fire.
+    clock = new Date(2026, 6, 27, 17, 31)
+    scheduler.tick()
+    expect(onFire).toHaveBeenCalledTimes(1)
+  })
+
+  it('fires a one-off only once, ever', () => {
+    const onFire = vi.fn()
+    let clock = MON_1730
+    const scheduler = createScheduler({
+      schedules: [{ id: 'once', runAt: MON_1730.toISOString() }],
+      onFire,
+      now: () => clock,
+    })
+    scheduler.tick()
+    // Same minute again, and a later matching-looking minute: still once.
+    scheduler.tick()
+    clock = new Date(MON_1730.getTime() + 60_000)
+    scheduler.tick()
+    expect(onFire).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips disabled schedules', () => {
+    const onFire = vi.fn()
+    const scheduler = createScheduler({
+      schedules: [{ id: 'x', cron: '30 17 * * *', enabled: false }],
+      onFire,
+      now: () => MON_1730,
+    })
+    scheduler.tick()
+    expect(onFire).not.toHaveBeenCalled()
+  })
+
+  it('start()/stop() drive ticks on the interval', () => {
+    vi.useFakeTimers()
+    try {
+      const onFire = vi.fn()
+      const scheduler = createScheduler({
+        schedules: [{ id: 'min', cron: '* * * * *' }],
+        onFire,
+        now: () => new Date(2026, 6, 27, 17, 30, 0),
+        intervalMs: 30_000,
+      })
+      scheduler.start()
+      vi.advanceTimersByTime(30_000)
+      expect(onFire).toHaveBeenCalledTimes(1) // once per minute despite 2 ticks
+      scheduler.stop()
+      vi.advanceTimersByTime(120_000)
+      expect(onFire).toHaveBeenCalledTimes(1) // stopped: no more fires
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('upcoming() reports the next run per schedule', () => {
+    const scheduler = createScheduler({
+      schedules: [
+        { id: 'eod', cron: '30 17 * * 1-5' },
+        { id: 'old', runAt: new Date(2020, 0, 1).toISOString() },
+      ],
+      onFire: () => {},
+      now: () => new Date(2026, 6, 27, 17, 31),
+    })
+    const up = scheduler.upcoming()
+    expect(up.find((u) => u.id === 'eod')?.at).toEqual(new Date(2026, 6, 28, 17, 30))
+    expect(up.find((u) => u.id === 'old')?.at).toBeNull()
+  })
+})