@svgrid/create 2.7.0 → 2.8.0

package/index.mjs

@@ -24,9 +24,13 @@ const TEMPLATES = {
     bundled: join(__dirname, 'templates', 'minimal'),
   },
   sveltekit: {
-    label: 'SvelteKit    - server load, URL-driven sort, form-action edits, theme picker',
+    label: 'SvelteKit    - server load, URL-driven sort, form-action edits, cookie auth + roles',
     bundled: join(__dirname, 'templates', 'sveltekit'),
   },
+  'pivot-dashboard': {
+    label: 'Pivot dashboard - pivot cube + linked chart + drill-through (needs @svgrid/enterprise)',
+    bundled: join(__dirname, 'templates', 'pivot-dashboard'),
+  },
   'admin-dashboard': {
     label: 'Admin dashboard - SvelteKit shell, multiple grids, deploy to Vercel',
     bundled: join(__dirname, 'templates', 'admin-dashboard'),

package/package.json

@@ -4,7 +4,7 @@
     "type": "commercial",
     "url": "https://svgrid.com/pricing"
   },
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Scaffold a Svelte app powered by SvGrid in one command: npm create @svgrid@latest",
   "type": "module",
   "license": "MIT",
@@ -36,7 +36,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@svgrid/grid": "^2.6.17"
+    "@svgrid/grid": "^2.7.0"
   },
   "scripts": {
     "sync-templates": "node sync-templates.mjs"

package/templates/pivot-dashboard/README.md

@@ -0,0 +1,74 @@
+# SvGrid pivot dashboard
+
+A pivot cube, a linked chart, and a drill-through rail over one fact table -
+the three pieces a reporting screen usually needs, wired so they cannot
+disagree with each other.
+
+```bash
+npm install
+npm run dev     # http://localhost:5173/
+```
+
+## What to try
+
+1. **Drag `Channel` into Rows** in the panel on the right. The cube, the chart
+   and any open drill all follow, because all three read the same layout.
+2. **Click any aggregated cell.** The rail opens with the exact rows behind that
+   number. The KPI at the top is recomputed from those rows, so it always equals
+   the cell you clicked.
+3. **Click a subtotal, then the grand total.** Same code path - a subtotal
+   simply contributes fewer filter terms, so the slice widens. The grand total
+   filters on nothing and returns all 1,800 facts.
+4. **Switch the measure** to `Units` in the Values well. The chart axis, the
+   rail KPI and the formatting all switch with it.
+5. **Click a bar** in the chart to drill that whole dimension value.
+
+## How the drill works
+
+A pivot cell is the intersection of a row path and a column path, and the two
+arrive in different shapes:
+
+- the **row** path is the chain of ancestors up to the clicked `PivotRow`,
+  matched positionally against `layout.rows`;
+- the **column** path is encoded in the column id - `pv__<dim>__<dim>__m<i>`,
+  where the trailing `m<i>` indexes into `layout.values`.
+
+`src/lib/drill.ts` decodes both into one `{ field: value }` filter and returns
+the facts that match every entry. Because the total is recomputed from those
+same facts rather than read off the grid, the rail and the cube cannot drift
+apart.
+
+That module is deliberately free of Svelte and of the grid packages, so you can
+unit-test your own reporting rules against it.
+
+## Where things are
+
+| File | Does |
+| --- | --- |
+| `src/lib/facts.ts` | The fact table. Seeded and deterministic. Swap `loadFacts` for your query. |
+| `src/lib/drill.ts` | Pure drill-through: cell -> filter -> facts. No Svelte, no grid imports. |
+| `src/routes/+page.server.ts` | Builds the facts on the server and sends them with the page. |
+| `src/routes/+page.svelte` | The dashboard: designer, chart and rail over one `facts` array. |
+| `src/routes/DrillRail.svelte` | The rail: KPIs plus a grid of the underlying rows. |
+| `src/routes/TrendChart.svelte` | The bar chart. Inline SVG-free DOM, styled with `--sg-*`. |
+
+## Licensing
+
+`SvPivotDesigner` is part of `@svgrid/enterprise`, which is commercial. The app
+runs unlicensed - it just nudges - so you can evaluate it before buying. Replace
+the key in `src/routes/+page.svelte`:
+
+```ts
+setLicenseKey('SVENTERPRISE-DEV-DEMO')
+```
+
+Pricing: https://svgrid.com/pricing
+
+## Going to production
+
+The facts are generated in-process. Point `loadFacts` at your warehouse and keep
+the aggregation on the server if the fact table is large - the browser should
+receive facts, not a database connection. Everything downstream takes `Fact[]`,
+so nothing else has to change.
+
+Full guide: https://svgrid.com/docs/enterprise/pivot/

package/templates/pivot-dashboard/_gitignore

@@ -0,0 +1,23 @@
+node_modules
+
+# Output
+.output
+.vercel
+.netlify
+.wrangler
+/.svelte-kit
+/build
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.*
+!.env.example
+!.env.test
+
+# Vite
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*

package/templates/pivot-dashboard/_package.json

@@ -0,0 +1,27 @@
+{
+  "name": "svgrid-pivot-dashboard",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "prepare": "svelte-kit sync || echo ''",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-auto": "^7.0.1",
+    "@sveltejs/kit": "^2.63.0",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "svelte": "^5.56.1",
+    "svelte-check": "^4.6.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16"
+  },
+  "dependencies": {
+    "@svgrid/grid": "^2.6.8",
+    "@svgrid/enterprise": "^2.6.4"
+  }
+}

package/templates/pivot-dashboard/src/app.css

@@ -0,0 +1,15 @@
+/* SvGrid theme. One of the 20 presets @svgrid/grid ships.
+ *
+ * Importing it as a stylesheet means the FIRST paint - and the server-rendered
+ * HTML - is already themed, before any JavaScript runs. The theme picker in the
+ * layout overrides these values at runtime by setting the same --sg-* custom
+ * properties on <html>.
+ *
+ * `npm create @svgrid@latest -- --theme <id>` rewrites the line between the
+ * markers, so pick a starting theme at scaffold time if you prefer. */
+/* svgrid-theme:start */
+@import '@svgrid/grid/themes/ember.css';
+/* svgrid-theme:end */
+
+* { box-sizing: border-box; }
+body { margin: 0; }

package/templates/pivot-dashboard/src/app.d.ts

@@ -0,0 +1,11 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface Platform {}
+	}
+}
+
+export {};

package/templates/pivot-dashboard/src/app.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en" data-theme="light">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="text-scale" content="scale" />
+		<script>
+			// Settle the theme before the first paint. Without this the server-rendered
+			// HTML shows one palette and the picker in +layout.svelte swaps it a frame
+			// later. With nothing saved yet we follow the OS.
+			try {
+				var saved = JSON.parse(localStorage.getItem('svgrid-theme') || 'null')
+				var fallback = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+				document.documentElement.dataset.theme = (saved && saved.mode) || fallback
+			} catch (e) {}
+		</script>
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

package/templates/pivot-dashboard/src/lib/drill.ts

@@ -0,0 +1,141 @@
+/**
+ * Drill-through: turn a clicked pivot cell back into the facts behind it.
+ *
+ * A pivot cell is the intersection of a row path and a column path. To find its
+ * source rows you need both, and the pivot gives them in two different shapes:
+ *
+ *   - the **row** path is the chain of ancestors up to the clicked `PivotRow`,
+ *     matched positionally against `layout.rows`;
+ *   - the **column** path is encoded in the column id, `pv__<dim>__<dim>__m<i>`,
+ *     where the trailing `m<i>` indexes into `layout.values`.
+ *
+ * Both decode to a plain `{ field: value }` filter, and the facts that match
+ * every entry are the ones that produced the cell. Because the total is
+ * recomputed from those same facts, the rail can never disagree with the grid.
+ *
+ * Kept free of Svelte and of the grid packages so it can be unit-tested on its
+ * own - see drill.test.ts.
+ */
+import type { Fact } from './facts'
+
+/** The subset of `PivotRow` this needs. Structural, so it does not drag the
+ *  enterprise types into a file that is otherwise pure. */
+export type PivotRowLike = {
+  __pivotId?: string
+  __pivotParentId?: string | null
+  __pivotLabel?: unknown
+  __pivotKind?: string
+}
+
+/** The subset of `PivotLayout` this needs. */
+export type PivotLayoutLike = {
+  rows: string[]
+  cols: string[]
+  values: { field: string }[]
+}
+
+export type Drill = {
+  /** Human label for the clicked row, for the rail heading. */
+  rowLabel: string
+  /** Field/value pairs the facts must match. */
+  filter: Record<string, string>
+  /** The facts behind the cell. */
+  facts: Fact[]
+  /** Which measure the clicked column showed. */
+  measure: string
+  /** That measure summed over `facts` - equal to the cell the user clicked. */
+  total: number
+}
+
+/**
+ * Walk from the clicked row up to the root, then match the chain positionally
+ * against `layout.rows`.
+ *
+ * The grand-total row filters on nothing: every fact contributed to it.
+ */
+export function rowFilterFor(
+  row: PivotRowLike,
+  allRows: PivotRowLike[],
+  layout: PivotLayoutLike,
+): Record<string, string> {
+  if (row.__pivotKind === 'grandTotal') return {}
+  const chain: PivotRowLike[] = []
+  let current: PivotRowLike | undefined = row
+  while (current) {
+    chain.unshift(current)
+    // Annotated: without it TypeScript infers `parentId` from `current`, which
+    // this line then reassigns, and the inference becomes circular.
+    const parentId: string | null | undefined = current.__pivotParentId
+    current = parentId ? allRows.find((r) => r.__pivotId === parentId) : undefined
+  }
+  const filter: Record<string, string> = {}
+  for (let i = 0; i < chain.length && i < layout.rows.length; i += 1) {
+    filter[layout.rows[i]!] = String(chain[i]!.__pivotLabel)
+  }
+  return filter
+}
+
+/**
+ * Decode a pivot column id into its column-axis filter and its measure.
+ *
+ * A subtotal column carries fewer dimension segments than `layout.cols` has,
+ * which is exactly right: fewer constraints means a wider slice.
+ */
+export function colFilterFor(
+  colId: string,
+  layout: PivotLayoutLike,
+): { filter: Record<string, string>; measure: string } {
+  const parts = colId.startsWith('pv__') ? colId.slice(4).split('__') : []
+  const last = parts[parts.length - 1]
+  const measureIndex = last?.startsWith('m') ? Number(last.slice(1)) : 0
+  const dimensions = parts.slice(0, Math.max(0, parts.length - 1))
+
+  const filter: Record<string, string> = {}
+  for (let i = 0; i < dimensions.length && i < layout.cols.length; i += 1) {
+    filter[layout.cols[i]!] = dimensions[i]!
+  }
+  return { filter, measure: layout.values[measureIndex]?.field ?? layout.values[0]?.field ?? 'revenue' }
+}
+
+/**
+ * The facts behind one clicked cell, plus the measure total over them.
+ *
+ * Works for leaf cells, subtotals and the grand total without special-casing:
+ * each simply contributes fewer filter entries, so the slice widens.
+ */
+export function drillThrough(
+  facts: Fact[],
+  row: PivotRowLike,
+  colId: string,
+  allRows: PivotRowLike[],
+  layout: PivotLayoutLike,
+): Drill {
+  const filter = { ...rowFilterFor(row, allRows, layout), ...colFilterFor(colId, layout).filter }
+  const { measure } = colFilterFor(colId, layout)
+
+  const matched = facts.filter((fact) => {
+    for (const [field, value] of Object.entries(filter)) {
+      if (String((fact as unknown as Record<string, unknown>)[field]) !== value) return false
+    }
+    return true
+  })
+
+  const total = matched.reduce(
+    (sum, fact) => sum + Number((fact as unknown as Record<string, unknown>)[measure] ?? 0),
+    0,
+  )
+
+  return {
+    rowLabel: row.__pivotKind === 'grandTotal' ? 'Grand total' : String(row.__pivotLabel ?? ''),
+    filter,
+    facts: matched,
+    measure,
+    total,
+  }
+}
+
+/** "EMEA / Germany / Q1" - the filter read back as a breadcrumb. */
+export function drillBreadcrumb(drill: Drill): string {
+  const parts = Object.values(drill.filter)
+  return parts.length ? parts.join(' / ') : 'All data'
+}

package/templates/pivot-dashboard/src/lib/facts.ts

@@ -0,0 +1,81 @@
+/**
+ * The fact table the whole dashboard is built on.
+ *
+ * A pivot summarises facts; a drill-through walks back to the exact facts
+ * behind one summarised cell. Both read this one array, which is why the number
+ * in the grid and the number in the drill rail can never disagree.
+ *
+ * Stands in for your warehouse. Swap `loadFacts` for a query and nothing
+ * downstream changes - the pivot, the chart and the drill all take `Fact[]`.
+ */
+
+export type Region = 'AMER' | 'EMEA' | 'APAC'
+export type Channel = 'Online' | 'Retail' | 'Wholesale'
+export type Quarter = 'Q1' | 'Q2' | 'Q3' | 'Q4'
+
+export type Fact = {
+  id: number
+  year: number
+  quarter: Quarter
+  region: Region
+  country: string
+  city: string
+  channel: Channel
+  customer: string
+  revenue: number
+  units: number
+}
+
+/** Which country and city belong to which region - keeps the seed coherent, so
+ *  drilling into EMEA never turns up a US city. */
+const TOPOLOGY: Record<Region, Record<string, string[]>> = {
+  AMER: { USA: ['New York', 'Austin', 'Seattle'], Canada: ['Toronto', 'Vancouver'] },
+  EMEA: { Germany: ['Berlin', 'Munich'], UK: ['London', 'Manchester'], France: ['Paris'] },
+  APAC: { Japan: ['Tokyo', 'Osaka'], India: ['Mumbai', 'Bangalore'] },
+}
+
+const CHANNELS: Channel[] = ['Online', 'Retail', 'Wholesale']
+const CUSTOMERS = [
+  'Acme Corp', 'Globex', 'Initech', 'Umbrella', 'Vandelay', 'Pied Piper',
+  'Hooli', 'Stark Industries', 'Tyrell', 'Wayne Ent.', 'Wonka', 'Cyberdyne',
+]
+
+/**
+ * Seeded PRNG, so every reload and every server instance produces the same
+ * dataset. With `Math.random` the SSR pass and the hydrated client would
+ * generate different numbers and Svelte would report a hydration mismatch.
+ */
+function makeRandom(seed: number): () => number {
+  let state = seed >>> 0
+  return () => {
+    state = (state * 1664525 + 1013904223) >>> 0
+    return state / 0xffffffff
+  }
+}
+
+/** Build the fact table. Deterministic for a given `count` and `seed`. */
+export function loadFacts(count = 1800, seed = 0xda7a101): Fact[] {
+  const rnd = makeRandom(seed)
+  const pick = <T>(items: readonly T[]): T => items[Math.floor(rnd() * items.length)]!
+  const regions = Object.keys(TOPOLOGY) as Region[]
+
+  const facts: Fact[] = []
+  for (let id = 1; id <= count; id += 1) {
+    const region = pick(regions)
+    const country = pick(Object.keys(TOPOLOGY[region]))
+    const city = pick(TOPOLOGY[region][country]!)
+    facts.push({
+      id,
+      year: pick([2025, 2026] as const),
+      quarter: pick(['Q1', 'Q2', 'Q3', 'Q4'] as const),
+      region,
+      country,
+      city,
+      channel: pick(CHANNELS),
+      customer: pick(CUSTOMERS),
+      revenue: Math.round(2_000 + rnd() * 48_000),
+      units: Math.round(5 + rnd() * 300),
+    })
+  }
+  return facts
+}

package/templates/pivot-dashboard/src/lib/theme.svelte.ts

@@ -0,0 +1,87 @@
+/**
+ * Runtime theme switching.
+ *
+ * `@svgrid/grid/themes` ships 20 presets and a `resolveThemeTokens(preset, mode)`
+ * helper that returns the `--sg-*` custom properties for a given preset and
+ * light/dark mode. Writing those onto `<html>` re-themes the grid live - there
+ * is nothing to rebuild and no stylesheet to swap.
+ *
+ * `app.css` imports one preset as a stylesheet so the very first paint (and the
+ * server-rendered HTML) already has a theme before any JS runs. The values set
+ * here override it once the user picks something.
+ */
+import {
+  getThemePreset,
+  resolveThemeTokens,
+  themePresets,
+  type ThemeMode,
+} from '@svgrid/grid/themes'
+
+/** Every preset, for the picker. */
+export const presets = themePresets.map((p) => ({ id: p.id, name: p.name }))
+
+const STORAGE_KEY = 'svgrid-theme'
+
+// `npm create @svgrid@latest -- --theme <id> [--dark|--light]` patches the two
+// values between these markers so the scaffolded app starts on the theme you
+// asked for. INITIAL_MODE is only the fallback: a saved choice wins over it, and
+// so does the OS preference when nobody has pinned a mode. The inline script in
+// `app.html` settles the same question before the first paint.
+/* svgrid-initial-theme:start */
+export const INITIAL_THEME = 'ember'
+export const INITIAL_MODE: ThemeMode = 'light'
+/* svgrid-initial-theme:end */
+
+type Saved = { id: string; mode: ThemeMode }
+
+function restore(): Saved {
+  const fallback: Saved = { id: INITIAL_THEME, mode: INITIAL_MODE }
+  if (typeof document === 'undefined') return fallback
+  // Trust whatever app.html's inline script settled on, so the picker agrees
+  // with what is already on screen.
+  const painted = document.documentElement.dataset.theme
+  if (painted === 'dark' || painted === 'light') fallback.mode = painted
+  try {
+    const saved = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? 'null') as Saved | null
+    if (!saved || typeof saved.id !== 'string') return fallback
+    if (!getThemePreset(saved.id)) return fallback
+    return { id: saved.id, mode: saved.mode === 'dark' ? 'dark' : 'light' }
+  } catch {
+    return fallback
+  }
+}
+
+class ThemeState {
+  #initial = restore()
+  id = $state(this.#initial.id)
+  mode = $state<ThemeMode>(this.#initial.mode)
+
+  /** Push the current selection onto <html> as CSS custom properties. */
+  apply() {
+    if (typeof document === 'undefined') return
+    const tokens = resolveThemeTokens(getThemePreset(this.id) ?? getThemePreset(INITIAL_THEME)!, this.mode)
+    const root = document.documentElement
+    for (const [key, value] of Object.entries(tokens)) root.style.setProperty(key, value)
+    // Lets the browser theme form controls and scrollbars to match, and keeps
+    // any `[data-theme='dark']` rules in your own CSS in step.
+    root.style.colorScheme = this.mode
+    root.dataset.theme = this.mode
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify({ id: this.id, mode: this.mode }))
+    } catch {
+      // Private mode, quota, a blocked origin - not worth breaking the page over.
+    }
+  }
+
+  set(id: string, mode: ThemeMode = this.mode) {
+    this.id = id
+    this.mode = mode
+    this.apply()
+  }
+
+  toggleMode() {
+    this.set(this.id, this.mode === 'dark' ? 'light' : 'dark')
+  }
+}
+
+export const theme = new ThemeState()

package/templates/pivot-dashboard/src/routes/+layout.svelte

@@ -0,0 +1,79 @@
+<script lang="ts">
+  import '../app.css'
+  import { theme, presets } from '$lib/theme.svelte'
+
+  let { children } = $props()
+
+  // Apply on mount so the picker's starting value wins over the stylesheet, and
+  // on every later change. Runs client-side only - the server-rendered HTML is
+  // already themed by the stylesheet import in app.css.
+  $effect(() => {
+    theme.apply()
+  })
+</script>
+
+<header class="bar">
+  <strong>Pivot dashboard</strong>
+
+  <label>
+    Theme
+    <select
+      value={theme.id}
+      onchange={(e) => theme.set(e.currentTarget.value)}
+      aria-label="Grid theme"
+    >
+      {#each presets as p (p.id)}
+        <option value={p.id}>{p.name}</option>
+      {/each}
+    </select>
+  </label>
+
+  <button type="button" onclick={() => theme.toggleMode()} aria-pressed={theme.mode === 'dark'}>
+    {theme.mode === 'dark' ? 'Dark' : 'Light'}
+  </button>
+
+</header>
+
+<main>
+  {@render children?.()}
+</main>
+
+<style>
+  .bar {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    flex-wrap: wrap;
+    padding: 0.75rem 1.25rem;
+    border-bottom: 1px solid var(--sg-border);
+    background: var(--sg-header-bg);
+    color: var(--sg-header-fg);
+    font-family: system-ui, sans-serif;
+  }
+  .bar label {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-size: 0.875rem;
+  }
+  .bar select,
+  .bar button {
+    font: inherit;
+    padding: 0.3rem 0.5rem;
+    border-radius: 6px;
+    border: 1px solid var(--sg-border);
+    background: var(--sg-bg);
+    color: var(--sg-fg);
+  }
+  .bar button {
+    cursor: pointer;
+    min-width: 4.5rem;
+  }
+  main {
+    padding: 1.25rem;
+    font-family: system-ui, sans-serif;
+    color: var(--sg-fg);
+    background: var(--sg-bg);
+    min-height: 100vh;
+  }
+</style>

package/templates/pivot-dashboard/src/routes/+page.server.ts

@@ -0,0 +1,11 @@
+import type { PageServerLoad } from './$types'
+import { loadFacts } from '$lib/facts'
+
+/**
+ * The fact table is built on the server and sent with the page.
+ *
+ * A pivot over a warehouse query belongs on the server: the browser should get
+ * facts, not a database connection. Swap `loadFacts` for your query and the
+ * rest of the dashboard is unchanged.
+ */
+export const load: PageServerLoad = () => ({ facts: loadFacts() })