@svgrid/enterprise 1.2.0 → 2.0.0

package/src/smart-shim.ts

@@ -1,105 +1,107 @@
-// Minimal globalThis.Smart shim so the vendored smart.export.js IIFE can
-// register Smart.Utilities.DataExporter without dragging in the rest of the
-// Smart UI runtime. DataExporter calls into Smart.Utilities.{Assign, Core.toDash}
-// at registration; the other namespaces (DateTime, NumberRenderer, Draw,
-// BigNumber, Complex) are guarded by `if (!Smart.Utilities.X) return e;` paths
-// inside the exporter and degrade gracefully when missing.
-//
-// We export a function instead of relying on import-side-effects so callers
-// can deterministically install the shim before the smart.export.js module
-// runs its IIFE.
-
-type SmartGlobal = {
-  Utilities: {
-    Assign(name: string, cls: unknown): void
-    Core: {
-      toDash(input: string): string
-    }
-    DataExporter?: new (
-      options: Record<string, unknown>,
-      groupBy?: ReadonlyArray<string>,
-      filterBy?: Record<string, unknown>,
-      conditionalFormatting?: unknown,
-    ) => SmartDataExporterInstance
-    [key: string]: unknown
-  }
-}
-
-/**
- * Shape of the image object Smart's xlsx writer expects from
- * `addImageToCell(...).image`. `base64` may be a full data URL; the
- * exporter strips the prefix.
- */
-export type SmartImageDescriptor = {
-  id: string
-  base64: string
-  imageType: string
-  width: number
-  height: number
-}
-
-export type SmartDataExporterInstance = {
-  /**
-   * Smart looks for these on the INSTANCE (not the constructor opts) at
-   * exportData() time. The wrapper sets them after `new DataExporter(...)`.
-   */
-  headerContent?: Array<{
-    cells: Record<string, unknown>
-    style?: Record<string, unknown>
-  }>
-  footerContent?: Array<{
-    cells: Record<string, unknown>
-    style?: Record<string, unknown>
-  }>
-  addImageToCell?: (
-    rowIndex: number,
-    dataField: string,
-    value: unknown,
-    rawValue: unknown,
-    row: Record<string, unknown>,
-    arrIndex: number,
-  ) => { image: SmartImageDescriptor; value?: unknown } | null
-  spreadsheets?: ReadonlyArray<{
-    label: string
-    dataSource: ReadonlyArray<Record<string, unknown>>
-    columns: ReadonlyArray<{ dataField: string; label: string }>
-    dataFields: ReadonlyArray<string>
-    style?: unknown
-  }>
-  exportData(
-    data: ReadonlyArray<Record<string, unknown>>,
-    format: string,
-    filename?: string,
-    callback?: (result: unknown) => void,
-  ): unknown
-}
-
-declare global {
-  interface Window {
-    Smart?: SmartGlobal
-  }
-}
-
-let installed = false
-
-export function installSmartShim(): void {
-  if (installed) return
-  if (typeof window === 'undefined') {
-    throw new Error('@svgrid/enterprise: installSmartShim() requires a browser environment')
-  }
-  const existing = window.Smart
-  const shim: SmartGlobal = existing ?? ({ Utilities: {} as SmartGlobal['Utilities'] })
-  shim.Utilities = shim.Utilities ?? ({} as SmartGlobal['Utilities'])
-  if (typeof shim.Utilities.Assign !== 'function') {
-    shim.Utilities.Assign = (name: string, cls: unknown) => {
-      ;(shim.Utilities as Record<string, unknown>)[name] = cls
-    }
-  }
-  if (!shim.Utilities.Core || typeof shim.Utilities.Core.toDash !== 'function') {
-    shim.Utilities.Core = {
-      toDash: (s: string) => s.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase()),
-    }
-  }
-  window.Smart = shim
-  installed = true
-}
+// Minimal globalThis.Smart shim so the vendored smart.export.js IIFE can
+// register Smart.Utilities.DataExporter without dragging in the rest of the
+// Smart UI runtime. DataExporter calls into Smart.Utilities.{Assign, Core.toDash}
+// at registration; the other namespaces (DateTime, NumberRenderer, Draw,
+// BigNumber, Complex) are guarded by `if (!Smart.Utilities.X) return e;` paths
+// inside the exporter and degrade gracefully when missing.
+//
+// We export a function instead of relying on import-side-effects so callers
+// can deterministically install the shim before the smart.export.js module
+// runs its IIFE.
+
+type SmartGlobal = {
+  Utilities: {
+    Assign(name: string, cls: unknown): void
+    Core: {
+      toDash(input: string): string
+    }
+    DataExporter?: new (
+      options: Record<string, unknown>,
+      groupBy?: ReadonlyArray<string>,
+      filterBy?: Record<string, unknown>,
+      conditionalFormatting?: unknown,
+    ) => SmartDataExporterInstance
+    [key: string]: unknown
+  }
+}
+
+/**
+ * Shape of the image object Smart's xlsx writer expects from
+ * `addImageToCell(...).image`. `base64` may be a full data URL; the
+ * exporter strips the prefix.
+ */
+export type SmartImageDescriptor = {
+  id: string
+  base64: string
+  imageType: string
+  width: number
+  height: number
+}
+
+export type SmartDataExporterInstance = {
+  /**
+   * Smart looks for these on the INSTANCE (not the constructor opts) at
+   * exportData() time. The wrapper sets them after `new DataExporter(...)`.
+   */
+  headerContent?: Array<{
+    cells: Record<string, unknown>
+    style?: Record<string, unknown>
+  }>
+  footerContent?: Array<{
+    cells: Record<string, unknown>
+    style?: Record<string, unknown>
+  }>
+  addImageToCell?: (
+    rowIndex: number,
+    dataField: string,
+    value: unknown,
+    rawValue: unknown,
+    row: Record<string, unknown>,
+    arrIndex: number,
+  ) => { image: SmartImageDescriptor; value?: unknown } | null
+  spreadsheets?: ReadonlyArray<{
+    label: string
+    dataSource: ReadonlyArray<Record<string, unknown>>
+    /** `format` is an optional Smart/Excel number-format token consumed by
+     *  the xlsx writer's `getXLSXFormat` to keep a column's cells typed. */
+    columns: ReadonlyArray<{ dataField: string; label: string; format?: string; width?: number }>
+    dataFields: ReadonlyArray<string>
+    style?: unknown
+  }>
+  exportData(
+    data: ReadonlyArray<Record<string, unknown>>,
+    format: string,
+    filename?: string,
+    callback?: (result: unknown) => void,
+  ): unknown
+}
+
+declare global {
+  interface Window {
+    Smart?: SmartGlobal
+  }
+}
+
+let installed = false
+
+export function installSmartShim(): void {
+  if (installed) return
+  if (typeof window === 'undefined') {
+    throw new Error('@svgrid/enterprise: installSmartShim() requires a browser environment')
+  }
+  const existing = window.Smart
+  const shim: SmartGlobal = existing ?? ({ Utilities: {} as SmartGlobal['Utilities'] })
+  shim.Utilities = shim.Utilities ?? ({} as SmartGlobal['Utilities'])
+  if (typeof shim.Utilities.Assign !== 'function') {
+    shim.Utilities.Assign = (name: string, cls: unknown) => {
+      ;(shim.Utilities as Record<string, unknown>)[name] = cls
+    }
+  }
+  if (!shim.Utilities.Core || typeof shim.Utilities.Core.toDash !== 'function') {
+    shim.Utilities.Core = {
+      toDash: (s: string) => s.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase()),
+    }
+  }
+  window.Smart = shim
+  installed = true
+}

package/src/sources/aggregate.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import type { EntitySchema } from '../schema'
+import { aggregateRows, chartFieldsFromSchema } from './aggregate'
+
+const rows = [
+  { id: 1, tier: 'pro', mrr: 100, active: true },
+  { id: 2, tier: 'pro', mrr: 300, active: true },
+  { id: 3, tier: 'free', mrr: 0, active: false },
+  { id: 4, tier: 'enterprise', mrr: 1000, active: true },
+]
+
+describe('aggregateRows', () => {
+  it('sums a measure by dimension, sorted desc', () => {
+    expect(aggregateRows(rows, { dimension: 'tier', measure: 'mrr', reduce: 'sum' })).toEqual([
+      { category: 'enterprise', value: 1000 },
+      { category: 'pro', value: 400 },
+      { category: 'free', value: 0 },
+    ])
+  })
+
+  it('counts rows per dimension (measure ignored); ties keep insertion order', () => {
+    expect(aggregateRows(rows, { dimension: 'tier', reduce: 'count' })).toEqual([
+      { category: 'pro', value: 2 },
+      { category: 'free', value: 1 },
+      { category: 'enterprise', value: 1 },
+    ])
+  })
+
+  it('averages, and handles min / max', () => {
+    expect(aggregateRows(rows, { dimension: 'tier', measure: 'mrr', reduce: 'avg' }).find((b) => b.category === 'pro')).toEqual({ category: 'pro', value: 200 })
+    expect(aggregateRows(rows, { dimension: 'tier', measure: 'mrr', reduce: 'max' }).find((b) => b.category === 'pro')).toEqual({ category: 'pro', value: 300 })
+    expect(aggregateRows(rows, { dimension: 'tier', measure: 'mrr', reduce: 'min' }).find((b) => b.category === 'pro')).toEqual({ category: 'pro', value: 100 })
+  })
+
+  it('groups a boolean dimension', () => {
+    const out = aggregateRows(rows, { dimension: 'active', reduce: 'count' })
+    expect(out).toEqual([{ category: 'true', value: 3 }, { category: 'false', value: 1 }])
+  })
+
+  it('with no dimension, returns a single grand-total bucket (a KPI)', () => {
+    expect(aggregateRows(rows, { reduce: 'count' })).toEqual([{ category: '', value: 4 }])
+    expect(aggregateRows(rows, { measure: 'mrr', reduce: 'sum' })).toEqual([{ category: '', value: 1400 }])
+    expect(aggregateRows(rows, { measure: 'mrr', reduce: 'max' })).toEqual([{ category: '', value: 1000 }])
+  })
+})
+
+describe('chartFieldsFromSchema', () => {
+  const schema: EntitySchema = {
+    name: 'customers', idField: 'id',
+    fields: [
+      { field: 'id', type: 'text', primaryKey: true },
+      { field: 'name', type: 'text' },
+      { field: 'tier', type: 'enum', options: [] },
+      { field: 'mrr', type: 'number' },
+      { field: 'seats', type: 'number' },
+      { field: 'active', type: 'boolean' },
+    ],
+  }
+
+  it('classifies dimensions (enum/boolean/text, non-key) and measures (number)', () => {
+    const f = chartFieldsFromSchema(schema)
+    expect(f.dimensions).toEqual(['name', 'tier', 'active'])
+    expect(f.measures).toEqual(['mrr', 'seats'])
+  })
+
+  it('prefers an enum dimension and the first measure as defaults', () => {
+    const f = chartFieldsFromSchema(schema)
+    expect(f.defaultDimension).toBe('tier')
+    expect(f.defaultMeasure).toBe('mrr')
+  })
+
+  it('falls back to boolean then text when there is no enum', () => {
+    const noEnum: EntitySchema = {
+      name: 't', idField: 'id',
+      fields: [{ field: 'id', type: 'text', primaryKey: true }, { field: 'label', type: 'text' }, { field: 'on', type: 'boolean' }],
+    }
+    expect(chartFieldsFromSchema(noEnum).defaultDimension).toBe('on')
+  })
+})

package/src/sources/aggregate.ts

@@ -0,0 +1,102 @@
+/**
+ * Aggregation for charts / dashboards: group rows by a dimension and reduce a
+ * measure into `{ category, value }` buckets. `aggregateRows` does it in memory;
+ * data sources can implement `getAggregate` to push the same shape down to the
+ * database (a `GROUP BY`) so it scales past what a page can hold. `SvSchemaChart`
+ * consumes either.
+ */
+import type { RowData, ServerFilterModel } from '@svgrid/grid'
+import type { EntitySchema } from '../schema'
+
+export type AggregateReduce = 'sum' | 'avg' | 'count' | 'min' | 'max'
+
+export type AggregateRequest = {
+  /**
+   * Field to group by (the chart's category axis). Omit it for a single grand
+   * total (a KPI) - the result is one bucket with an empty `category`.
+   */
+  dimension?: string
+  /** Field to reduce. Ignored for `count`. */
+  measure?: string
+  reduce: AggregateReduce
+  /** Optional filter, same shape the grid emits. */
+  filterModel?: ServerFilterModel
+}
+
+export type AggregateBucket = { category: string; value: number }
+
+/** A data source that can aggregate server-side (e.g. a SQL `GROUP BY`). */
+export type AggregateSource = {
+  getAggregate(request: AggregateRequest): Promise<AggregateBucket[]>
+}
+
+const num = (v: unknown) => {
+  const n = Number(v)
+  return Number.isFinite(n) ? n : 0
+}
+
+/** Group `rows` by `dimension` and reduce `measure`; sorted by value desc. */
+export function aggregateRows<T extends RowData>(
+  rows: ReadonlyArray<T>,
+  request: AggregateRequest,
+): AggregateBucket[] {
+  const { dimension, measure, reduce } = request
+  const sum = new Map<string, number>()
+  const count = new Map<string, number>()
+  const ext = new Map<string, number>() // running min/max
+
+  for (const row of rows) {
+    // No dimension -> a single grand-total bucket (KPI).
+    const category = dimension ? String(row[dimension] ?? '') : ''
+    count.set(category, (count.get(category) ?? 0) + 1)
+    if (reduce !== 'count') {
+      const v = num(measure ? row[measure] : 0)
+      sum.set(category, (sum.get(category) ?? 0) + v)
+      if (reduce === 'min') ext.set(category, Math.min(ext.get(category) ?? Infinity, v))
+      if (reduce === 'max') ext.set(category, Math.max(ext.get(category) ?? -Infinity, v))
+    }
+  }
+
+  const buckets: AggregateBucket[] = [...count.keys()].map((category) => {
+    const c = count.get(category)!
+    let value: number
+    if (reduce === 'count') value = c
+    else if (reduce === 'avg') value = c ? (sum.get(category) ?? 0) / c : 0
+    else if (reduce === 'min' || reduce === 'max') value = ext.get(category) ?? 0
+    else value = sum.get(category) ?? 0
+    return { category, value }
+  })
+
+  return buckets.sort((a, b) => b.value - a.value)
+}
+
+/**
+ * Pick chart-able fields from a schema: **dimensions** to group by (enum /
+ * boolean / text, non-key) and **measures** to reduce (number). Defaults favor a
+ * low-cardinality dimension (enum, then boolean) and the first numeric measure.
+ */
+export function chartFieldsFromSchema(schema: EntitySchema): {
+  dimensions: string[]
+  measures: string[]
+  defaultDimension: string | null
+  defaultMeasure: string | null
+} {
+  const nonKey = schema.fields.filter((f) => !f.primaryKey)
+  const dimensions = nonKey
+    .filter((f) => f.type === 'enum' || f.type === 'boolean' || f.type === 'text')
+    .map((f) => f.field)
+  const measures = nonKey.filter((f) => f.type === 'number').map((f) => f.field)
+
+  const preferred =
+    nonKey.find((f) => f.type === 'enum')?.field ??
+    nonKey.find((f) => f.type === 'boolean')?.field ??
+    dimensions[0] ??
+    null
+
+  return {
+    dimensions,
+    measures,
+    defaultDimension: preferred,
+    defaultMeasure: measures[0] ?? null,
+  }
+}

package/src/sources/auth-supabase.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createSupabaseAuth, type AuthState } from './auth-supabase'
+
+/** A supabase-js-like auth client with controllable session + spies. */
+function makeClient(initialSession: { user: { id: string; email?: string } } | null = null) {
+  let cb: ((event: string, session: unknown) => void) | undefined
+  const unsubscribe = vi.fn()
+  type AuthResult = { error: { message: string } | null }
+  const ok = async (): Promise<AuthResult> => ({ error: null })
+  const client = {
+    auth: {
+      getSession: vi.fn(async () => ({ data: { session: initialSession } })),
+      onAuthStateChange: vi.fn((fn: (e: string, s: unknown) => void) => {
+        cb = fn
+        return { data: { subscription: { unsubscribe } } }
+      }),
+      signInWithPassword: vi.fn(ok),
+      signUp: vi.fn(ok),
+      signOut: vi.fn(ok),
+    },
+  }
+  return { client, unsubscribe, fire: (session: unknown) => cb?.('x', session) }
+}
+
+const track = () => {
+  const states: AuthState[] = []
+  return { states, onChange: (s: AuthState) => states.push(s) }
+}
+
+describe('createSupabaseAuth', () => {
+  it('resolves the current session on init', async () => {
+    const { client } = makeClient({ user: { id: 'u1', email: 'a@b.co' } })
+    const { states, onChange } = track()
+    createSupabaseAuth({ client, onChange })
+    await vi.waitFor(() => expect(states.at(-1)?.user).toEqual({ id: 'u1', email: 'a@b.co' }))
+    expect(states.at(-1)?.loading).toBe(false)
+  })
+
+  it('starts in a loading, signed-out state', () => {
+    const { client } = makeClient(null)
+    const { states, onChange } = track()
+    createSupabaseAuth({ client, onChange })
+    expect(states[0]).toEqual({ user: null, loading: true, error: null })
+  })
+
+  it('updates when auth state changes (sign in elsewhere)', async () => {
+    const { client, fire } = makeClient(null)
+    const { states, onChange } = track()
+    createSupabaseAuth({ client, onChange })
+    await vi.waitFor(() => expect(states.at(-1)?.loading).toBe(false))
+    fire({ user: { id: 'u2', email: 'x@y.co' } })
+    expect(states.at(-1)?.user).toEqual({ id: 'u2', email: 'x@y.co' })
+  })
+
+  it('signIn calls signInWithPassword and surfaces errors', async () => {
+    const { client } = makeClient(null)
+    client.auth.signInWithPassword.mockResolvedValueOnce({ error: { message: 'bad creds' } })
+    const { states, onChange } = track()
+    const auth = createSupabaseAuth({ client, onChange })
+    await auth.signIn('a@b.co', 'pw')
+    expect(client.auth.signInWithPassword).toHaveBeenCalledWith({ email: 'a@b.co', password: 'pw' })
+    expect(states.at(-1)).toMatchObject({ error: 'bad creds', loading: false })
+  })
+
+  it('signUp and signOut call through', async () => {
+    const { client } = makeClient(null)
+    const auth = createSupabaseAuth({ client, onChange: () => {} })
+    await auth.signUp('a@b.co', 'pw')
+    await auth.signOut()
+    expect(client.auth.signUp).toHaveBeenCalledWith({ email: 'a@b.co', password: 'pw' })
+    expect(client.auth.signOut).toHaveBeenCalled()
+  })
+
+  it('dispose unsubscribes from auth changes', () => {
+    const { client, unsubscribe } = makeClient(null)
+    const auth = createSupabaseAuth({ client, onChange: () => {} })
+    auth.dispose()
+    expect(unsubscribe).toHaveBeenCalled()
+  })
+})

package/src/sources/auth-supabase.ts

@@ -0,0 +1,87 @@
+/**
+ * createSupabaseAuth - a tiny reactive controller over Supabase Auth, so a
+ * Studio screen can require a signed-in user. You bring the `supabase-js` client
+ * (BYO, no dependency); this tracks the session and exposes sign in / up / out.
+ * Pair it with `SvAuthGate` to gate the UI, and with Row-Level Security to scope
+ * data per user - auth establishes *who*, RLS enforces *what they can see*.
+ *
+ *     const auth = createSupabaseAuth({ client, onChange: (s) => (authState = s) })
+ *     await auth.signIn(email, password)
+ *     // ... auth.signOut(); auth.dispose() on unmount
+ */
+import { nudgeEnterprise } from '../license'
+
+export type AuthUser = { id: string; email?: string }
+
+export type AuthState = {
+  /** The signed-in user, or null. */
+  user: AuthUser | null
+  /** True during the initial session check or an in-flight auth call. */
+  loading: boolean
+  /** Last auth error message, or null. */
+  error: string | null
+}
+
+type Session = { user: { id: string; email?: string } } | null
+
+/** The slice of a `supabase-js` client's `auth` this needs. */
+export type SupabaseAuthClientLike = {
+  auth: {
+    getSession(): Promise<{ data: { session: Session } }>
+    onAuthStateChange(cb: (event: string, session: Session) => void): {
+      data: { subscription: { unsubscribe(): void } }
+    }
+    signInWithPassword(c: { email: string; password: string }): Promise<{ error: { message: string } | null }>
+    signUp(c: { email: string; password: string }): Promise<{ error: { message: string } | null }>
+    signOut(): Promise<{ error: { message: string } | null }>
+  }
+}
+
+export type SupabaseAuthConfig = {
+  client: SupabaseAuthClientLike
+  onChange: (state: AuthState) => void
+}
+
+export type SupabaseAuthController = {
+  signIn(email: string, password: string): Promise<void>
+  signUp(email: string, password: string): Promise<void>
+  signOut(): Promise<void>
+  getState(): AuthState
+  dispose(): void
+}
+
+const userOf = (session: Session): AuthUser | null =>
+  session?.user ? { id: session.user.id, email: session.user.email } : null
+
+export function createSupabaseAuth(config: SupabaseAuthConfig): SupabaseAuthController {
+  nudgeEnterprise('Studio') // soft-gate; never blocks
+  let state: AuthState = { user: null, loading: true, error: null }
+  const emit = () => config.onChange({ ...state })
+  const set = (patch: Partial<AuthState>) => {
+    state = { ...state, ...patch }
+    emit()
+  }
+
+  emit() // initial loading state
+
+  // Resolve the current session, then keep it in sync.
+  config.client.auth.getSession().then(({ data }) => set({ user: userOf(data.session), loading: false }))
+  const sub = config.client.auth.onAuthStateChange((_event, session) =>
+    set({ user: userOf(session), loading: false }),
+  )
+
+  const run = async (op: () => Promise<{ error: { message: string } | null }>) => {
+    set({ loading: true, error: null })
+    const { error } = await op()
+    // On success the user arrives via onAuthStateChange; just clear loading.
+    set(error ? { loading: false, error: error.message } : { loading: false })
+  }
+
+  return {
+    signIn: (email, password) => run(() => config.client.auth.signInWithPassword({ email, password })),
+    signUp: (email, password) => run(() => config.client.auth.signUp({ email, password })),
+    signOut: () => run(() => config.client.auth.signOut()),
+    getState: () => ({ ...state }),
+    dispose: () => sub.data.subscription.unsubscribe(),
+  }
+}

package/src/sources/dashboard.kpi.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest'
+import { kpiSeries, sparklinePoints, seriesDelta, formatKpiValue } from './dashboard'
+
+describe('kpiSeries', () => {
+  const rows = [
+    { stage: '2026-01', value: 10 },
+    { stage: '2026-01', value: 5 },
+    { stage: '2026-03', value: 20 },
+    { stage: '2026-02', value: 8 },
+    { stage: '', value: 99 }, // empty bucket key is skipped
+  ]
+  it('buckets by trendField (sorted) and reduces the measure', () => {
+    expect(kpiSeries(rows, { trendField: 'stage', measure: 'value', reduce: 'sum' })).toEqual([15, 8, 20])
+  })
+  it('counts rows per bucket when reduce is count', () => {
+    expect(kpiSeries(rows, { trendField: 'stage', reduce: 'count' })).toEqual([2, 1, 1])
+  })
+})
+
+describe('sparklinePoints', () => {
+  it('maps values into a w x h box with the max at the top', () => {
+    const pts = sparklinePoints([0, 10], 100, 20, 0).split(' ')
+    expect(pts).toHaveLength(2)
+    expect(pts[0]).toBe('0.0,20.0') // min -> bottom
+    expect(pts[1]).toBe('100.0,0.0') // max -> top, last x at width
+  })
+  it('is empty for no data', () => {
+    expect(sparklinePoints([])).toBe('')
+  })
+})
+
+describe('seriesDelta', () => {
+  it('is the percent change from first non-zero to last', () => {
+    expect(seriesDelta([100, 150])).toBe(50)
+    expect(seriesDelta([0, 100, 50])).toBe(-50) // first non-zero is 100, last is 50
+  })
+  it('is null when it cannot be computed', () => {
+    expect(seriesDelta([5])).toBeNull()
+    expect(seriesDelta([0, 0])).toBeNull()
+  })
+})
+
+describe('formatKpiValue', () => {
+  it('formats currency / percent / compact / number', () => {
+    expect(formatKpiValue(1234.5, 'currency')).toBe('$1,235')
+    expect(formatKpiValue(42.5, 'percent')).toBe('42.5%')
+    expect(formatKpiValue(12500, 'compact')).toBe('12.5K')
+    expect(formatKpiValue(1234.5, 'number')).toBe('1,234.5')
+  })
+})

package/src/sources/dashboard.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+import type { EntitySchema } from '../schema'
+import { dashboardFromSchema, reduceValue } from './dashboard'
+
+const rows = [
+  { id: '1', tier: 'pro', mrr: 100 },
+  { id: '2', tier: 'free', mrr: 0 },
+  { id: '3', tier: 'pro', mrr: 300 },
+]
+
+describe('reduceValue', () => {
+  it('counts rows regardless of measure', () => {
+    expect(reduceValue(rows, { reduce: 'count' })).toBe(3)
+    expect(reduceValue(rows, { measure: 'mrr', reduce: 'count' })).toBe(3)
+  })
+  it('sums / averages / min / max a measure', () => {
+    expect(reduceValue(rows, { measure: 'mrr', reduce: 'sum' })).toBe(400)
+    expect(reduceValue(rows, { measure: 'mrr', reduce: 'avg' })).toBeCloseTo(133.33, 1)
+    expect(reduceValue(rows, { measure: 'mrr', reduce: 'min' })).toBe(0)
+    expect(reduceValue(rows, { measure: 'mrr', reduce: 'max' })).toBe(300)
+  })
+  it('is 0 for an empty set', () => {
+    expect(reduceValue([], { measure: 'mrr', reduce: 'sum' })).toBe(0)
+  })
+})
+
+describe('dashboardFromSchema', () => {
+  const schema: EntitySchema = {
+    name: 'customers',
+    label: 'Customer',
+    fields: [
+      { field: 'id', type: 'text', primaryKey: true },
+      { field: 'tier', type: 'enum', options: [{ value: 'free', label: 'Free' }, { value: 'pro', label: 'Pro' }] },
+      { field: 'mrr', type: 'number' },
+    ],
+  }
+
+  it('proposes count + measure KPIs and a chart on the default dimension', () => {
+    const { widgets } = dashboardFromSchema(schema)
+    const kpis = widgets.filter((w) => w.kind === 'kpi')
+    const charts = widgets.filter((w) => w.kind === 'chart')
+    expect(kpis.some((w) => w.reduce === 'count')).toBe(true)
+    expect(kpis.some((w) => w.kind === 'kpi' && w.measure === 'mrr' && w.reduce === 'sum')).toBe(true)
+    expect(charts).toHaveLength(1)
+    expect(charts[0]).toMatchObject({ kind: 'chart', dimension: 'tier', measure: 'mrr' })
+  })
+
+  it('degrades to a count-only dashboard when there is no measure', () => {
+    const noMeasure: EntitySchema = {
+      name: 'tags',
+      fields: [
+        { field: 'id', type: 'text', primaryKey: true },
+        { field: 'kind', type: 'enum', options: [{ value: 'a', label: 'A' }] },
+      ],
+    }
+    const { widgets } = dashboardFromSchema(noMeasure)
+    expect(widgets.filter((w) => w.kind === 'kpi')).toHaveLength(1)
+    const chart = widgets.find((w) => w.kind === 'chart')
+    expect(chart).toMatchObject({ reduce: 'count' })
+  })
+})