@svgrid/enterprise 1.2.0 → 2.0.0

package/src/SvSchedule.svelte

@@ -0,0 +1,156 @@
+<script lang="ts">
+  /**
+   * SvSchedule - a month event-calendar over an entity's rows. Each row with a
+   * `dateField` value is placed as an event chip on its day; `titleField` is the
+   * chip label and an optional enum `colorField` tints it. A real scheduling view
+   * (appointments / events / bookings / shifts) - the signature calendar that makes
+   * a Studio app read like a product, not a report.
+   *
+   * Pure presentation over plain rows + an EntitySchema (same inputs as SvBoard /
+   * SvSchemaChart), so the generated app and the designer preview match.
+   */
+  import type { EntitySchema } from './schema'
+
+  type Row = Record<string, unknown>
+
+  let {
+    schema,
+    rows = [],
+    dateField,
+    titleField,
+    colorField,
+    onSelect,
+    loading = false,
+    height,
+  }: {
+    schema: EntitySchema
+    rows?: ReadonlyArray<Row>
+    /** The date / datetime field that places a row on the calendar. */
+    dateField: string
+    /** Field shown as the event chip label. */
+    titleField: string
+    /** Optional enum field whose option color tints the chip. */
+    colorField?: string
+    onSelect?: (id: string) => void
+    /** Dim the grid + show a loading note during first load. */
+    loading?: boolean
+    height?: number
+  } = $props()
+
+  const idField = $derived(schema.idField ?? schema.fields.find((f) => f.primaryKey)?.field ?? 'id')
+  const colorMap = $derived.by(() => {
+    const m = new Map<string, string>()
+    schema.fields.find((f) => f.field === colorField)?.options?.forEach((o) => { if (o.color) m.set(String(o.value), o.color) })
+    return m
+  })
+
+  const WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
+  const startOfMonth = (d: Date) => new Date(d.getFullYear(), d.getMonth(), 1)
+  const addMonths = (d: Date, n: number) => new Date(d.getFullYear(), d.getMonth() + n, 1)
+  const sameDay = (a: Date, b: Date) => a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate()
+  function parse(v: unknown): Date | null {
+    if (v == null || v === '') return null
+    const d = new Date(String(v))
+    return Number.isNaN(d.getTime()) ? null : d
+  }
+
+  const events = $derived(rows.map((r) => ({ r, d: parse(r[dateField]) })).filter((e): e is { r: Row; d: Date } => e.d != null))
+  // Anchor the view to the BUSIEST month (most events) so the calendar always opens
+  // on data, not an empty month; ties break to the earliest. Falls back to today.
+  const anchor = $derived.by(() => {
+    if (events.length === 0) return startOfMonth(new Date())
+    const buckets = new Map<string, { start: Date; n: number }>()
+    for (const e of events) {
+      const key = `${e.d.getFullYear()}-${e.d.getMonth()}`
+      const cur = buckets.get(key)
+      if (cur) cur.n += 1
+      else buckets.set(key, { start: startOfMonth(e.d), n: 1 })
+    }
+    return [...buckets.values()].sort((a, b) => b.n - a.n || a.start.getTime() - b.start.getTime())[0]!.start
+  })
+  let offset = $state(0)
+  const viewMonth = $derived(addMonths(anchor, offset))
+  const monthLabel = $derived(viewMonth.toLocaleString(undefined, { month: 'long', year: 'numeric' }))
+
+  const days = $derived.by(() => {
+    const first = viewMonth
+    const start = new Date(first)
+    start.setDate(1 - first.getDay()) // back to the Sunday on/before the 1st
+    return Array.from({ length: 42 }, (_, i) => { const d = new Date(start); d.setDate(start.getDate() + i); return d })
+  })
+  const eventsOn = (d: Date) => events.filter((e) => sameDay(e.d, d))
+  const today = new Date()
+</script>
+
+<div class="sv-sched" style:height={height != null ? `${height}px` : undefined}>
+  <header class="sv-sched__bar">
+    <strong class="sv-sched__month">{monthLabel}</strong>
+    <div class="sv-sched__nav">
+      <button type="button" class="sv-sched__btn" aria-label="Previous month" onclick={() => (offset -= 1)}>&lsaquo;</button>
+      <button type="button" class="sv-sched__btn sv-sched__today" onclick={() => (offset = 0)}>Today</button>
+      <button type="button" class="sv-sched__btn" aria-label="Next month" onclick={() => (offset += 1)}>&rsaquo;</button>
+    </div>
+  </header>
+  <div class="sv-sched__weekdays">
+    {#each WEEKDAYS as w (w)}<span class="sv-sched__wd">{w}</span>{/each}
+  </div>
+  <div class="sv-sched__grid">
+    {#each days as d (d.getTime())}
+      {@const evs = eventsOn(d)}
+      {@const outside = d.getMonth() !== viewMonth.getMonth()}
+      <div class="sv-sched__cell" class:is-outside={outside} class:is-today={sameDay(d, today)}>
+        <span class="sv-sched__daynum">{d.getDate()}</span>
+        <div class="sv-sched__evs">
+          {#each evs.slice(0, 3) as e (String(e.r[idField]))}
+            {@const c = colorMap.get(String(e.r[colorField ?? ''])) ?? 'var(--sg-accent, #6366f1)'}
+            {#if onSelect}
+              <button type="button" class="sv-sched__ev sv-sched__ev--btn" style:--c={c} title={String(e.r[titleField] ?? '')} onclick={() => onSelect(String(e.r[idField]))}>
+                <span class="sv-sched__ev-dot"></span>{String(e.r[titleField] ?? '(untitled)')}
+              </button>
+            {:else}
+              <span class="sv-sched__ev" style:--c={c} title={String(e.r[titleField] ?? '')}>
+                <span class="sv-sched__ev-dot"></span>{String(e.r[titleField] ?? '(untitled)')}
+              </span>
+            {/if}
+          {/each}
+          {#if evs.length > 3}<span class="sv-sched__more">+{evs.length - 3} more</span>{/if}
+        </div>
+      </div>
+    {/each}
+  </div>
+  {#if loading}
+    <div class="sv-sched__overlay"><span class="sv-sched__spinner" aria-hidden="true"></span>Loading…</div>
+  {:else if rows.length === 0}
+    <div class="sv-sched__overlay">No events scheduled yet.</div>
+  {/if}
+</div>
+
+<style>
+  .sv-sched {
+    position: relative;
+    display: flex; flex-direction: column; min-height: 420px; box-sizing: border-box;
+    background: var(--sg-bg, #fff); border: 1px solid var(--sg-border, #e6e8ec); border-radius: 12px; overflow: hidden;
+  }
+  .sv-sched__overlay { position: absolute; inset: 46px 0 0; display: flex; align-items: center; justify-content: center; gap: 10px; background: color-mix(in srgb, var(--sg-bg, #fff) 72%, transparent); backdrop-filter: blur(1px); color: var(--sg-muted, #64748b); font-size: 13.5px; }
+  .sv-sched__spinner { width: 18px; height: 18px; border-radius: 50%; border: 2px solid var(--sg-border, #e6e8ec); border-top-color: var(--sg-accent, #6366f1); animation: sv-sched-spin 0.7s linear infinite; }
+  @keyframes sv-sched-spin { to { transform: rotate(360deg); } }
+  .sv-sched__ev--btn { appearance: none; width: 100%; text-align: left; border: none; font: inherit; }
+  .sv-sched__bar { display: flex; align-items: center; justify-content: space-between; padding: 12px 14px; border-bottom: 1px solid var(--sg-border, #e6e8ec); }
+  .sv-sched__month { font-size: 15px; font-weight: 750; color: var(--sg-fg, #0f172a); }
+  .sv-sched__nav { display: flex; gap: 4px; }
+  .sv-sched__btn { min-width: 30px; height: 30px; padding: 0 10px; display: inline-flex; align-items: center; justify-content: center; font: inherit; font-size: 13px; font-weight: 600; color: var(--sg-fg, #0f172a); background: var(--sg-header-bg, #f6f7f9); border: 1px solid var(--sg-border, #e6e8ec); border-radius: 8px; cursor: pointer; }
+  .sv-sched__btn:hover { background: color-mix(in srgb, var(--sg-accent, #6366f1) 10%, var(--sg-header-bg, #f6f7f9)); }
+  .sv-sched__weekdays { display: grid; grid-template-columns: repeat(7, 1fr); border-bottom: 1px solid var(--sg-border, #e6e8ec); }
+  .sv-sched__wd { padding: 7px 8px; font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; color: var(--sg-muted, #94a3b8); text-align: right; }
+  .sv-sched__grid { flex: 1; display: grid; grid-template-columns: repeat(7, 1fr); grid-auto-rows: 1fr; min-height: 0; }
+  .sv-sched__cell { border-right: 1px solid var(--sg-border, #eef0f3); border-bottom: 1px solid var(--sg-border, #eef0f3); padding: 4px 5px; min-height: 62px; display: flex; flex-direction: column; gap: 3px; overflow: hidden; }
+  .sv-sched__cell:nth-child(7n) { border-right: 0; }
+  .sv-sched__cell.is-outside { background: color-mix(in srgb, var(--sg-header-bg, #f6f7f9) 55%, transparent); }
+  .sv-sched__daynum { align-self: flex-end; font-size: 11.5px; font-weight: 600; color: var(--sg-muted, #64748b); padding: 1px 3px; }
+  .sv-sched__cell.is-outside .sv-sched__daynum { color: var(--sg-muted, #b6bdc7); }
+  .sv-sched__cell.is-today .sv-sched__daynum { background: var(--sg-accent, #6366f1); color: #fff; border-radius: 999px; min-width: 18px; text-align: center; }
+  .sv-sched__evs { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+  .sv-sched__ev { display: flex; align-items: center; gap: 5px; padding: 2px 6px; font-size: 11px; font-weight: 600; border-radius: 5px; cursor: pointer; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--c, var(--sg-accent, #6366f1)); background: color-mix(in srgb, var(--c, #6366f1) 13%, transparent); }
+  .sv-sched__ev-dot { width: 6px; height: 6px; border-radius: 50%; background: var(--c, var(--sg-accent, #6366f1)); flex: none; }
+  .sv-sched__more { font-size: 10.5px; font-weight: 600; color: var(--sg-muted, #94a3b8); padding: 0 4px; }
+</style>

package/src/SvSchemaChart.svelte

@@ -0,0 +1,233 @@
+<script lang="ts" module>
+  type ChartRow = Record<string, unknown>
+</script>
+
+<script lang="ts" generics="TData extends ChartRow">
+  /**
+   * SvSchemaChart - a reusable chart bound to an `EntitySchema`. It picks
+   * chart-able fields from the schema (dimensions to group by, measures to
+   * reduce), renders built-in controls, and draws with `SvGridChart`.
+   *
+   * Aggregation is either client-side (pass `rows`) or server-side (pass
+   * `getAggregate`, e.g. a SQL / Supabase source's `GROUP BY`), so it scales
+   * past what a page holds. Click a category to drill (`onDrill`).
+   */
+  import { SvGridChart, SvGridDropdown, type ChartSpec, type ChartType, type ChartSelection } from '@svgrid/grid'
+  import { titleCase, type EntitySchema } from './schema'
+  import {
+    aggregateRows,
+    chartFieldsFromSchema,
+    type AggregateBucket,
+    type AggregateReduce,
+    type AggregateRequest,
+  } from './sources/aggregate'
+
+  type FilterModel = AggregateRequest['filterModel']
+
+  type Props = {
+    schema: EntitySchema<TData>
+    /** Client-side data to aggregate. Ignored when `getAggregate` is set. */
+    rows?: ReadonlyArray<TData>
+    /** Server-side aggregation (a data source's `getAggregate`). Takes precedence. */
+    getAggregate?: (request: AggregateRequest) => Promise<AggregateBucket[]>
+    /** Filter passed to `getAggregate`. */
+    filterModel?: FilterModel
+    dimension?: string
+    measure?: string
+    reduce?: AggregateReduce
+    type?: ChartType
+    /** Show the built-in dimension / measure / type controls. Default true. */
+    controls?: boolean
+    height?: number
+    width?: number
+    dataLabels?: boolean
+    formatValue?: (v: number) => string
+    onDrill?: (category: string, dimension: string) => void
+    /** Bump to re-fetch server aggregates (e.g. after a mutation). */
+    refreshKey?: unknown
+    /** Brand color. Bars / lines use it; pie slices grouped by an enum use the
+     *  enum's own option colors (matching status badges). */
+    accent?: string
+  }
+
+  let {
+    schema,
+    rows,
+    getAggregate,
+    filterModel,
+    dimension,
+    measure,
+    reduce,
+    type,
+    controls = true,
+    height = 300,
+    width = 460,
+    dataLabels = true,
+    formatValue,
+    onDrill,
+    refreshKey,
+    accent,
+  }: Props = $props()
+
+  const fields = $derived(chartFieldsFromSchema(schema as EntitySchema))
+
+  // Render the chart at its ACTUAL pixel width so the SVG viewBox maps 1:1 to
+  // screen pixels (scale factor = 1). Otherwise the SVG stretches to fill a wide
+  // block and its text (font-size in user units) scales up with it - "fonts that
+  // grow with the chart". Measured width keeps labels at a fixed px size, like
+  // the grid. Falls back to the `width` prop until the first measurement.
+  let measuredW = $state(0)
+  let plotEl: HTMLDivElement | undefined = $state()
+  $effect(() => {
+    const el = plotEl
+    if (!el || typeof ResizeObserver === 'undefined') return
+    const ro = new ResizeObserver((entries) => {
+      const w = Math.round(entries[0]?.contentRect.width ?? 0)
+      if (w > 0 && w !== measuredW) measuredW = w
+    })
+    ro.observe(el)
+    return () => ro.disconnect()
+  })
+
+  let dim = $state('')
+  let msr = $state('')
+  let red = $state<AggregateReduce>('sum')
+  let ctype = $state<ChartType>('bar')
+  let seeded = false
+
+  // Seed once from the props, then keep the dimension/measure valid for the schema.
+  $effect(() => {
+    if (!seeded) {
+      seeded = true
+      if (dimension) dim = dimension
+      if (measure) msr = measure
+      if (reduce) red = reduce
+      if (type) ctype = type
+    }
+    if (!dim || !fields.dimensions.includes(dim)) dim = fields.defaultDimension ?? fields.dimensions[0] ?? ''
+    if ((!msr || !fields.measures.includes(msr)) && fields.measures.length) msr = fields.defaultMeasure ?? fields.measures[0] ?? ''
+  })
+
+  const labelOf = (field: string) => schema.fields.find((f) => f.field === field)?.label ?? titleCase(field)
+  const measureLabel = $derived(
+    red === 'count' ? 'Count' : `${red[0]!.toUpperCase() + red.slice(1)} ${labelOf(msr)}`,
+  )
+
+  let serverBuckets = $state<AggregateBucket[]>([])
+  let fetchToken = 0
+  $effect(() => {
+    if (!getAggregate || !dim) return
+    void refreshKey // re-run after a mutation
+    const req: AggregateRequest = { dimension: dim, measure: msr || undefined, reduce: red, filterModel }
+    const token = ++fetchToken
+    getAggregate(req).then((bs) => {
+      if (token === fetchToken) serverBuckets = bs
+    })
+  })
+
+  const buckets = $derived(
+    getAggregate
+      ? serverBuckets
+      : dim
+        ? aggregateRows((rows ?? []) as ReadonlyArray<ChartRow>, { dimension: dim, measure: msr || undefined, reduce: red })
+        : [],
+  )
+
+  // Options for the custom dropdown controls.
+  const dimOptions = $derived(fields.dimensions.map((d) => ({ value: d, label: labelOf(d) })))
+  const measureOptions = $derived(fields.measures.map((m) => ({ value: m, label: labelOf(m) })))
+  const reduceOptions = [
+    { value: 'count', label: 'Count' }, { value: 'sum', label: 'Sum' }, { value: 'avg', label: 'Average' },
+    { value: 'min', label: 'Min' }, { value: 'max', label: 'Max' },
+  ]
+  const typeOptions = [
+    { value: 'bar', label: 'Bar' }, { value: 'pie', label: 'Pie' }, { value: 'line', label: 'Line' }, { value: 'area', label: 'Area' },
+    { value: 'radar', label: 'Radar' }, { value: 'funnel', label: 'Funnel' }, { value: 'waterfall', label: 'Waterfall' }, { value: 'treemap', label: 'Treemap' },
+  ]
+  // Cartesian types get x/y axis titles; radial / area-partition types don't.
+  const CARTESIAN_TYPES = new Set<ChartType>(['bar', 'line', 'area', 'waterfall'])
+
+  // Per-category colors from the dimension's enum options (status/stage/etc), in
+  // bucket order, so a pie's slices match the grid's badge colors.
+  const categoryColors = $derived.by<string[] | undefined>(() => {
+    const opts = schema.fields.find((f) => f.field === dim)?.options
+    if (!opts?.length) return undefined
+    return buckets.map((b) => {
+      const opt = opts.find((o) => String(o.value) === String(b.category))
+      return opt?.color || accent || '#6366f1'
+    })
+  })
+
+  const spec = $derived.by<ChartSpec>(() => {
+    const s: ChartSpec = {
+      type: ctype,
+      categories: buckets.map((b) => b.category),
+      // Bars / lines / areas take the brand accent; pie ignores series color and
+      // uses the palette (semantic enum colors when available).
+      series: [{ label: measureLabel, values: buckets.map((b) => b.value), ...(accent ? { color: accent } : {}) }],
+      width: measuredW || width,
+      height,
+      ...(categoryColors ? { palette: categoryColors } : {}),
+    }
+    if (ctype === 'pie') s.innerRadius = 0.6
+    // Treemap reads a tree, not a category/series pair - build a flat one from
+    // the same buckets (each dimension value is a leaf sized by the measure).
+    if (ctype === 'treemap') s.treemap = { name: measureLabel, children: buckets.map((b) => ({ name: b.category, value: b.value })) }
+    if (CARTESIAN_TYPES.has(ctype)) {
+      s.xAxisTitle = labelOf(dim)
+      s.yAxisTitle = measureLabel
+    }
+    return s
+  })
+
+  function onSelect(sel: ChartSelection) {
+    onDrill?.(String(sel.category), dim)
+  }
+</script>
+
+<div class="sv-chart">
+  {#if controls}
+    <div class="sv-chart__controls">
+      <div class="sv-chart__ctrl">
+        <span>Group by</span>
+        <div class="sv-chart__dd"><SvGridDropdown options={dimOptions} value={dim} autoOpen={false} onChange={(v) => (dim = String(v))} /></div>
+      </div>
+      <div class="sv-chart__ctrl">
+        <span>Measure</span>
+        <div class="sv-chart__dd"><SvGridDropdown options={reduceOptions} value={red} autoOpen={false} onChange={(v) => (red = v as AggregateReduce)} /></div>
+      </div>
+      {#if red !== 'count' && fields.measures.length}
+        <div class="sv-chart__ctrl">
+          <span>of</span>
+          <div class="sv-chart__dd"><SvGridDropdown options={measureOptions} value={msr} autoOpen={false} onChange={(v) => (msr = String(v))} /></div>
+        </div>
+      {/if}
+      <div class="sv-chart__ctrl">
+        <span>Type</span>
+        <div class="sv-chart__dd"><SvGridDropdown options={typeOptions} value={ctype} autoOpen={false} onChange={(v) => (ctype = v as ChartType)} /></div>
+      </div>
+    </div>
+  {/if}
+
+  {#if dim}
+    <div class="sv-chart__plot" bind:this={plotEl}>
+      <SvGridChart {spec} {dataLabels} {formatValue} {onSelect} />
+    </div>
+  {:else}
+    <p class="sv-chart__empty">No chart-able fields in this schema.</p>
+  {/if}
+</div>
+
+<style>
+  .sv-chart { display: flex; flex-direction: column; gap: 10px; }
+  .sv-chart__plot { width: 100%; min-width: 0; }
+  .sv-chart__controls { display: flex; flex-wrap: wrap; gap: 10px; }
+  .sv-chart__ctrl { display: flex; flex-direction: column; gap: 3px; font-size: 11px; font-weight: 600; color: var(--sg-muted, #666); }
+  .sv-chart__dd {
+    position: relative; height: 32px; min-width: 130px;
+    border: 1px solid var(--sg-border, #ccc); border-radius: 8px; background: var(--sg-input-bg, #fff);
+  }
+  .sv-chart__dd :global(.sv-grid-dropdown),
+  .sv-chart__dd :global(.sv-grid-dropdown-trigger) { background: transparent; border-radius: 8px; }
+  .sv-chart__empty { color: var(--sg-muted, #888); font-size: 13px; padding: 24px; text-align: center; }
+</style>

package/src/SvSchemaDashboard.svelte

@@ -0,0 +1,130 @@
+<script lang="ts" module>
+  type DashRow = Record<string, unknown>
+</script>
+
+<script lang="ts" generics="TData extends DashRow">
+  /**
+   * SvSchemaDashboard - a schema-driven dashboard: KPI tiles + charts composed
+   * from a declarative `DashboardSpec` (defaults to `dashboardFromSchema`). It's
+   * a data *view*, not a page builder - the spec is plain data and every chart is
+   * an `SvSchemaChart` with its controls off. KPI tiles reduce over the passed
+   * `rows`; charts prefer a server `getAggregate` when given, else `rows`.
+   */
+  import SvSchemaChart from './SvSchemaChart.svelte'
+  import type { EntitySchema } from './schema'
+  import { dashboardFromSchema, reduceValue, type DashboardSpec } from './sources/dashboard'
+  import type { AggregateBucket, AggregateRequest, AggregateReduce } from './sources/aggregate'
+
+  type Props = {
+    schema: EntitySchema<TData>
+    /** Rows for KPI tiles (and charts when there's no `getAggregate`). */
+    rows?: ReadonlyArray<TData>
+    /**
+     * Server-side aggregation (a data source's `getAggregate`). When set, KPI
+     * tiles AND charts are computed server-side (KPIs via a dimension-less
+     * request), so they're correct over the whole table, not just a page.
+     */
+    getAggregate?: (request: AggregateRequest) => Promise<AggregateBucket[]>
+    /** Filter applied to every widget (KPIs + charts), same shape the grid emits. */
+    filterModel?: AggregateRequest['filterModel']
+    /** Widget layout. Defaults to a sensible set from the schema. */
+    spec?: DashboardSpec
+    /** Bump to re-fetch server aggregates after a mutation. */
+    refreshKey?: unknown
+    onDrill?: (category: string, dimension: string) => void
+    title?: string
+  }
+
+  let { schema, rows, getAggregate, filterModel, spec, refreshKey, onDrill, title }: Props = $props()
+
+  const widgets = $derived((spec ?? dashboardFromSchema(schema as EntitySchema)).widgets)
+  const data = $derived((rows ?? []) as ReadonlyArray<TData>)
+
+  const compact = new Intl.NumberFormat(undefined, { notation: 'compact', maximumFractionDigits: 1 })
+  const fmt = (v: number, f?: (v: number) => string) => (f ? f(v) : compact.format(v))
+
+  // Server KPIs: when `getAggregate` is set, fetch each KPI as a dimension-less
+  // aggregate (a grand total over the whole table), re-running on refresh/filter.
+  let serverKpis = $state<number[]>([])
+  let kpiToken = 0
+  $effect(() => {
+    if (!getAggregate) return
+    void refreshKey
+    const reqs = widgets.map((w) =>
+      w.kind === 'kpi' ? getAggregate({ measure: w.measure, reduce: w.reduce, filterModel }) : null,
+    )
+    const token = ++kpiToken
+    Promise.all(reqs.map((r) => (r ? r.then((bs) => bs[0]?.value ?? 0) : Promise.resolve(0)))).then((vals) => {
+      if (token === kpiToken) serverKpis = vals
+    })
+  })
+  const kpiValue = (w: { measure?: string; reduce: AggregateReduce }, i: number) =>
+    getAggregate ? (serverKpis[i] ?? 0) : reduceValue(data, { measure: w.measure, reduce: w.reduce })
+</script>
+
+<section class="dash">
+  {#if title}<h3 class="dash__title">{title}</h3>{/if}
+  <div class="dash__grid">
+    {#each widgets as w, i (i)}
+      {#if w.kind === 'kpi'}
+        <div class="dash__kpi">
+          <span class="dash__kpi-label">{w.label}</span>
+          <span class="dash__kpi-value">{fmt(kpiValue(w, i), w.format)}</span>
+        </div>
+      {:else}
+        <div class="dash__chart" style="grid-column: span {Math.min(w.span ?? 2, 3)}">
+          {#if w.label}<span class="dash__chart-label">{w.label}</span>{/if}
+          <SvSchemaChart
+            schema={schema as EntitySchema}
+            rows={getAggregate ? undefined : (data as ReadonlyArray<DashRow>)}
+            {getAggregate}
+            {filterModel}
+            dimension={w.dimension}
+            measure={w.measure}
+            reduce={w.reduce}
+            type={w.type}
+            controls={false}
+            height={230}
+            width={420}
+            {refreshKey}
+            onDrill={(category, dimension) => onDrill?.(category, dimension)}
+          />
+        </div>
+      {/if}
+    {/each}
+  </div>
+</section>
+
+<style>
+  .dash { display: flex; flex-direction: column; gap: 12px; }
+  .dash__title { margin: 0; font-size: 15px; font-weight: 650; color: var(--sg-fg, #0f172a); }
+  .dash__grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(190px, 1fr));
+    /* Size rows to content; otherwise implicit auto rows stretch to fill a
+       bounded-height container and shrink below each widget, overlapping them. */
+    grid-auto-rows: max-content;
+    gap: 12px;
+    align-items: start;
+  }
+  .dash__kpi {
+    display: flex; flex-direction: column; gap: 6px;
+    padding: 16px 16px 18px;
+    border: 1px solid var(--sg-border, #e6e8ec); border-radius: 12px;
+    background: var(--sg-bg, #fff);
+    box-shadow: 0 1px 2px rgba(15, 23, 42, 0.05);
+  }
+  .dash__kpi-label { font-size: 12.5px; font-weight: 550; color: var(--sg-muted, #64748b); }
+  .dash__kpi-value { font-size: 26px; font-weight: 720; letter-spacing: -0.02em; color: var(--sg-fg, #0f172a); }
+  .dash__chart {
+    display: flex; flex-direction: column; gap: 8px;
+    padding: 14px 14px 12px; min-width: 0;
+    border: 1px solid var(--sg-border, #e6e8ec); border-radius: 12px;
+    background: var(--sg-bg, #fff);
+    box-shadow: 0 1px 2px rgba(15, 23, 42, 0.05);
+  }
+  .dash__chart-label { font-size: 13px; font-weight: 600; color: var(--sg-fg, #0f172a); }
+  @media (max-width: 620px) {
+    .dash__chart { grid-column: span 1 !important; }
+  }
+</style>

package/src/ai-export-pdf.test.ts

@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Capture exactly what exportGrid receives (so we don't need pdfmake / the DOM).
+const calls: Array<{ format: string; rows?: unknown[]; groupBy?: string[] }> = []
+vi.mock('./export', () => ({
+  exportGrid: async (_api: unknown, opts: { format: string; rows?: unknown[]; groupBy?: string[] }) => {
+    calls.push({ format: opts.format, rows: opts.rows as unknown[], groupBy: opts.groupBy })
+  },
+}))
+
+import { aiExport, setAIProvider, mockAIProvider } from './ai'
+import { setLicenseKey } from './license'
+
+type Order = { country: string; company: string; product: string; quantity: number; price: number }
+const rows: Order[] = Array.from({ length: 120 }, (_, i) => ({
+  country: ['USA', 'UK', 'Germany'][i % 3]!,
+  company: `Co${i}`,
+  product: 'Widget',
+  quantity: 5 + (i % 50),
+  price: Math.round((10 + ((i * 41) % 480)) * 100) / 100, // spread 10..490
+}))
+
+function makeApi() {
+  return {
+    getData: () => rows,
+    // Simulate the grid returning EVERYTHING (the reactive-filter bug we route around).
+    getDisplayedRows: () => rows,
+    getSelectedRows: () => [],
+    getColumns: () => [
+      { id: 'country', field: 'country', header: 'Country', visible: true },
+      { id: 'company', field: 'company', header: 'Company', visible: true },
+      { id: 'product', field: 'product', header: 'Product', visible: true },
+      { id: 'quantity', field: 'quantity', header: 'Qty', visible: true },
+      { id: 'price', field: 'price', header: 'Price', visible: true },
+    ],
+    getState: () => ({ grouping: [] }),
+    clearAllFilters: vi.fn(),
+    clearSort: vi.fn(),
+    setFilter: vi.fn(),
+    setSort: vi.fn(),
+    setGroupBy: vi.fn(),
+  } as any
+}
+
+beforeEach(() => {
+  calls.length = 0
+  setLicenseKey('SVENTERPRISE-DEV-TEST')
+  setAIProvider(mockAIProvider)
+})
+
+describe('aiExport - the demo 203 "grouped PDF" query', () => {
+  it('parses the plan and exports non-empty, filtered, grouped rows', async () => {
+    const plan = await aiExport(makeApi(), 'export orders over $300 as a grouped PDF by country')
+
+    expect(plan.format).toBe('pdf')
+    expect(plan.groupBy).toEqual(['country'])
+    expect(plan.filters).toContainEqual({ field: 'price', operator: 'greaterThan', value: '300' })
+
+    // exportGrid was called with real, filtered rows (not the empty grid view).
+    expect(calls).toHaveLength(1)
+    expect(calls[0]!.format).toBe('pdf')
+    expect(calls[0]!.groupBy).toEqual(['country'])
+    const exported = calls[0]!.rows as Order[]
+    expect(exported.length).toBeGreaterThan(0)
+    expect(exported.every((r) => r.price > 300)).toBe(true)
+    // Rows are contiguous by country (group order preserved).
+    const countries = exported.map((r) => r.country)
+    const firstSeen = [...new Set(countries)]
+    const contiguous = countries.join('|')
+    for (const c of firstSeen) {
+      expect(contiguous).toMatch(new RegExp(`(?:^|\\|)${c}(?:\\|${c})*(?:\\||$)`))
+    }
+  })
+})

package/src/ai-export-xlsx.test.ts

@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Real exportGrid runs (NOT mocked). Capture the xlsx parts / avoid the DOM.
+const captured: { parts: Record<string, string> } = { parts: {} }
+vi.mock('jszip', () => ({
+  default: class {
+    file(p: string, d: string) {
+      captured.parts[p] = d
+    }
+    async generateAsync() {
+      return new Blob([])
+    }
+  },
+}))
+vi.mock('./export-serialize', async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>
+  return { ...actual, downloadBlobFile: () => {}, downloadTextFile: () => {} }
+})
+
+import { aiExport, setAIProvider, mockAIProvider } from './ai'
+import { setLicenseKey } from './license'
+
+// Mirrors the real makeOrders shape - crucially includes `inStock` (boolean)
+// and `quantity`/`index` (numbers that never exceed 300), so the mock must
+// target `price` for "$300", not a boolean or a count.
+type Order = {
+  id: string
+  index: number
+  country: string
+  company: string
+  product: string
+  inStock: boolean
+  quantity: number
+  price: number
+}
+const rows: Order[] = Array.from({ length: 120 }, (_, i) => ({
+  id: `o${i}`,
+  index: i + 1,
+  country: ['USA', 'UK', 'Germany'][i % 3]!,
+  company: `Co${i}`,
+  product: 'Widget',
+  inStock: i % 3 !== 0,
+  quantity: 5 + (i % 50), // max 54 - never > 300
+  price: Math.round((10 + ((i * 41) % 480)) * 100) / 100, // spread 10..490
+}))
+
+function makeApi() {
+  return {
+    getData: () => rows,
+    getDisplayedRows: () => rows,
+    getSelectedRows: () => [],
+    getColumns: () => [
+      { id: 'country', field: 'country', header: 'Country', visible: true },
+      { id: 'company', field: 'company', header: 'Company', visible: true },
+      { id: 'product', field: 'product', header: 'Product', visible: true },
+      { id: 'quantity', field: 'quantity', header: 'Qty', visible: true },
+      { id: 'price', field: 'price', header: 'Price', visible: true, format: { type: 'currency', currency: 'USD' } },
+    ],
+    getState: () => ({ grouping: [] }),
+    getColumnPinning: () => ({ left: [], right: [] }),
+    clearAllFilters: vi.fn(),
+    clearSort: vi.fn(),
+    setFilter: vi.fn(),
+    setSort: vi.fn(),
+    setGroupBy: vi.fn(),
+  } as any
+}
+
+beforeEach(() => {
+  captured.parts = {}
+  setLicenseKey('SVENTERPRISE-DEV-TEST')
+  setAIProvider(mockAIProvider)
+})
+
+describe('aiExport - "export orders over $300" (xlsx default)', () => {
+  it('produces a non-empty xlsx via the real export path', async () => {
+    const plan = await aiExport(makeApi(), 'export orders over $300')
+    expect(plan.format).toBe('xlsx')
+    expect(plan.filters).toContainEqual({ field: 'price', operator: 'greaterThan', value: '300' })
+
+    const sheet = captured.parts['xl/worksheets/sheet1.xml']
+    expect(sheet).toBeTruthy()
+    // header row + at least one data row
+    const rowCount = (sheet!.match(/<row /g) ?? []).length
+    expect(rowCount).toBeGreaterThan(1)
+  })
+})