@svgrid/create 2.5.0 → 2.6.0

package/README.md

@@ -43,19 +43,20 @@ pnpm create @svgrid my-app -t minimal
 | Template | Stack | Best for |
 | --- | --- | --- |
 | `minimal` | Vite + Svelte 5 + SvGrid | Dropping a grid into something quickly |
+| `sveltekit` | SvelteKit, server load + form actions | Learning how a grid fits SvelteKit, or starting one |
 | `admin-dashboard` | SvelteKit + Tailwind + SvGrid, deploy to Vercel | A real dashboard / internal tool |
 
 ## Options
 
 | Flag | Description |
 | --- | --- |
-| `--template`, `-t` | `minimal` or `admin-dashboard` |
+| `--template`, `-t` | `minimal`, `sveltekit` or `admin-dashboard` |
 | `--theme <id>` | One of `@svgrid/grid`'s 20 built-in presets - shadcn, Tailwind, Material, Excel, Fluent, and more (default: `tailwind`) |
-| `--dark` / `--light` | Start in dark or light mode. `minimal` follows the OS when neither is given |
+| `--dark` / `--light` | Pin the starting mode. `minimal` and `sveltekit` follow the visitor's OS when neither is given |
 | `--force`, `-f` | Scaffold into a non-empty directory |
 | `--help`, `-h` | Show usage |
 
-Either template prompts for a theme and a light/dark mode when run
+Every template prompts for a theme and a light/dark mode when run
 interactively, or takes them as flags:
 
 ```bash
@@ -63,8 +64,10 @@ npm create @svgrid@latest my-app -- -t admin-dashboard --theme material --light
 npm create @svgrid@latest my-app -- -t minimal --theme nord --dark
 ```
 
-Both ship a working toggle, so the choice is a starting point rather than
-something you are stuck with.
+All three ship a working toggle, so the choice is a starting point rather than
+something you are stuck with. `sveltekit` goes further and puts all 20 presets
+in a picker in the header, so you can try them against your own data without
+rescaffolding.
 
 Then:
 

package/index.mjs

@@ -23,6 +23,10 @@ const TEMPLATES = {
     label: 'Minimal      - Vite + Svelte 5 + SvGrid, one page',
     bundled: join(__dirname, 'templates', 'minimal'),
   },
+  sveltekit: {
+    label: 'SvelteKit    - server load, URL-driven sort, form-action edits, theme picker',
+    bundled: join(__dirname, 'templates', 'sveltekit'),
+  },
   'admin-dashboard': {
     label: 'Admin dashboard - SvelteKit shell, multiple grids, deploy to Vercel',
     bundled: join(__dirname, 'templates', 'admin-dashboard'),
@@ -81,7 +85,8 @@ ${Object.entries(TEMPLATES)
 
 ${color('bold', 'Options')}
   --theme <id>       One of: ${THEME_IDS.join(', ')} (default: tailwind).
-  --dark / --light   Start in dark or light mode (default: dark).
+  --dark / --light   Pin the starting mode. Left out, minimal and sveltekit
+                     follow the visitor's OS; admin-dashboard starts dark.
   --force            Scaffold into a non-empty directory.
 
 ${color('bold', 'Examples')}
@@ -175,6 +180,62 @@ async function applyTheme(destDir, choice) {
   if (marked.test(cssText)) {
     await writeFile(cssPath, cssText.replace(marked, `/* svgrid-theme:start */\n${css}\n/* svgrid-theme:end */`))
   }
+
+  // Templates with a RUNTIME theme picker keep the starting selection in TS, so
+  // the picker opens on the theme that was scaffolded rather than disagreeing
+  // with the stylesheet above. Absent in templates without a picker, where the
+  // missing file makes this a no-op.
+  const tsPath = join(destDir, 'src', 'lib', 'theme.svelte.ts')
+  const tsText = await readFile(tsPath, 'utf8').catch(() => null)
+  if (tsText == null) return
+  const tsMarked = /\/\* svgrid-initial-theme:start \*\/([\s\S]*?)\/\* svgrid-initial-theme:end \*\//
+  if (!tsMarked.test(tsText)) return
+  // Only the preset here. The mode is left to applyModeSvelteKit, which pins it
+  // only when one was actually asked for.
+  const body = tsText.match(tsMarked)[1].replace(
+    /export const INITIAL_THEME = '[^']*'/,
+    `export const INITIAL_THEME = '${preset.id}'`,
+  )
+  await writeFile(
+    tsPath,
+    tsText.replace(
+      tsMarked,
+      `/* svgrid-initial-theme:start */${body}/* svgrid-initial-theme:end */`,
+    ),
+  )
+}
+
+/** sveltekit settles its start mode in an inline script in `src/app.html`,
+ *  falling back to the OS preference, exactly as minimal does. Pin it only when
+ *  light or dark was actually asked for. The picker in the layout reads the
+ *  attribute that script sets, so both halves have to agree. */
+async function applyModeSvelteKit(destDir, choice) {
+  if (!choice || !choice.explicitMode) return
+
+  const htmlPath = join(destDir, 'src', 'app.html')
+  const html = await readFile(htmlPath, 'utf8').catch(() => null)
+  if (html != null) {
+    await writeFile(
+      htmlPath,
+      html
+        .replace(`<html lang="en" data-theme="light">`, `<html lang="en" data-theme="${choice.mode}">`)
+        .replace(
+          `var fallback = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'`,
+          `var fallback = '${choice.mode}'`,
+        ),
+    )
+  }
+
+  const tsPath = join(destDir, 'src', 'lib', 'theme.svelte.ts')
+  const ts = await readFile(tsPath, 'utf8').catch(() => null)
+  if (ts == null) return
+  await writeFile(
+    tsPath,
+    ts.replace(
+      /export const INITIAL_MODE: ThemeMode = '[^']*'/,
+      `export const INITIAL_MODE: ThemeMode = '${choice.mode}'`,
+    ),
+  )
 }
 
 /** admin-dashboard defaults to dark (see app.html / src/lib/theme.ts /
@@ -330,7 +391,7 @@ async function main() {
       Object.entries(TEMPLATES).forEach(([, t], i) => {
         stdout.write(`   ${color('cyan', String(i + 1))}. ${t.label}\n`)
       })
-      const pick = await ask('\nChoose a template (1-2):', '1')
+      const pick = await ask(`\nChoose a template (1-${Object.keys(TEMPLATES).length}):`, '1')
       template = Object.keys(TEMPLATES)[Number(pick) - 1] ?? 'minimal'
     } else {
       template = 'minimal'
@@ -378,13 +439,15 @@ async function main() {
   await applyTheme(destDir, themeChoice)
   await applyMode(destDir, themeChoice)
   await applyModeMinimal(destDir, themeChoice)
+  await applyModeSvelteKit(destDir, themeChoice)
 
   // 5. Next steps.
   const rel = isAbsolute(target) || target.startsWith('.') ? target : `./${target}`
   stdout.write(`\n${color('green', '✔')} Scaffolded ${color('bold', projectName)} (${template}) into ${rel}\n`)
   if (themeChoice) {
-    // minimal only pins a mode when one was asked for; otherwise it reads the
-    // OS preference at load, so reporting "dark" here would be a lie.
+    // minimal and sveltekit only pin a mode when one was asked for; otherwise
+    // they read the OS preference at load, so reporting "dark" here would be a
+    // lie. admin-dashboard is dark by default either way.
     const pinned = themeChoice.explicitMode || template === 'admin-dashboard'
     const mode = pinned ? themeChoice.mode : 'follows your OS'
     stdout.write(`  ${color('dim', 'theme')} ${themeChoice.name} (${mode})\n`)

package/package.json

@@ -4,7 +4,7 @@
     "type": "commercial",
     "url": "https://svgrid.com/pricing"
   },
-  "version": "2.5.0",
+  "version": "2.6.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.5.0"
+    "@svgrid/grid": "^2.6.9"
   },
   "scripts": {
     "sync-templates": "node sync-templates.mjs"

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

@@ -1,184 +1,184 @@
-@import 'tailwindcss';
-
-/* Tailwind's `dark:` modifier follows the `data-theme` attribute the layout
- * writes onto <html>, so utility classes and the grid's own --sg-* tokens
- * switch together. */
-@custom-variant dark (&:where(html[data-theme='dark'], html[data-theme='dark'] *));
-
-/* ---------------------------------------------------------------------------
- * SvGrid theme tokens - one of @svgrid/grid's 20 built-in presets (pick one
- * with `npm create @svgrid@latest -- --theme <id> [--dark]`, or edit the
- * values below by hand). The dashboard shell reads them through the --app-*
- * aliases further down, so the whole app themes as one, not just the grid.
- * ------------------------------------------------------------------------- */
-/* svgrid-theme:start */
-:root {
-  --sg-bg: #ffffff;
-  --sg-fg: #0f172a;
-  --sg-muted: #64748b;
-  --sg-border: #e2e8f0;
-  --sg-header-bg: #f8fafc;
-  --sg-header-fg: #0f172a;
-  --sg-bg-subtle: #f8fafc;
-  --sg-row-alt-bg: #ffffff;
-  --sg-row-hover-bg: #f1f5f9;
-  --sg-selection-bg: #e0e7ff;
-  --sg-input-bg: #ffffff;
-  --sg-input-border: #e2e8f0;
-  --sg-accent: #4f46e5;
-  --sg-on-accent: #ffffff;
-  --sg-radius: 6px;
-  --sg-font: Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
-  --sg-scrollbar-bg: #f8fafc;
-  --sg-scrollbar-border: #e2e8f0;
-  --sg-scrollbar-thumb: #64748b;
-  --sg-scrollbar-thumb-hover: #0f172a;
-  --sg-scrollbar-thumb-active: #0f172a;
-  --sg-scrollbar-arrow: #64748b;
-  --sg-scrollbar-arrow-hover: #0f172a;
-  --sg-scrollbar-arrow-hover-bg: #f1f5f9;
-  --sg-scrollbar-arrow-active: #0f172a;
-  --sg-scrollbar-arrow-active-bg: #e0e7ff;
-  --sg-scrollbar-arrow-disabled: #e2e8f0;
-  color-scheme: light;
-}
-:root[data-theme='dark'] {
-  --sg-bg: #0f172a;
-  --sg-fg: #f8fafc;
-  --sg-muted: #94a3b8;
-  --sg-border: #334155;
-  --sg-header-bg: #1e293b;
-  --sg-header-fg: #f8fafc;
-  --sg-bg-subtle: #1e293b;
-  --sg-row-alt-bg: #0f172a;
-  --sg-row-hover-bg: #1e293b;
-  --sg-selection-bg: #312e81;
-  --sg-input-bg: #0f172a;
-  --sg-input-border: #334155;
-  --sg-accent: #818cf8;
-  --sg-on-accent: #18181b;
-  --sg-radius: 6px;
-  --sg-font: Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
-  --sg-scrollbar-bg: #1e293b;
-  --sg-scrollbar-border: #334155;
-  --sg-scrollbar-thumb: #94a3b8;
-  --sg-scrollbar-thumb-hover: #f8fafc;
-  --sg-scrollbar-thumb-active: #f8fafc;
-  --sg-scrollbar-arrow: #94a3b8;
-  --sg-scrollbar-arrow-hover: #f8fafc;
-  --sg-scrollbar-arrow-hover-bg: #1e293b;
-  --sg-scrollbar-arrow-active: #f8fafc;
-  --sg-scrollbar-arrow-active-bg: #312e81;
-  --sg-scrollbar-arrow-disabled: #334155;
-  color-scheme: dark;
-}
-/* svgrid-theme:end */
-
-/* Dashboard shell aliases - map the chrome to the grid tokens above, so any
- * theme (light or dark, whichever preset) reskins the whole page as one. */
-:root {
-  --app-bg: var(--sg-row-alt-bg);
-  --app-panel: var(--sg-bg);
-  --app-border: var(--sg-border);
-  --app-fg: var(--sg-fg);
-  --app-muted: var(--sg-muted);
-  --app-accent: var(--sg-accent);
-  /* Text that sits ON the accent. Every preset declares this, and it is NOT
-     always white: shadcn dark uses a near-white accent (#fafafa) with near-black
-     text. Hardcoding #fff here made the active nav item invisible. */
-  --app-on-accent: var(--sg-on-accent);
-}
-
-html,
-body {
-  background: var(--app-bg);
-  color: var(--app-fg);
-  font-family: var(--sg-font, Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial,
-    sans-serif);
-}
-
-/* ---------------------------------------------------------------------------
- * Optional polish. The grid themes itself from the --sg-* tokens above, so it
- * already follows light / dark with no extra CSS. These rules only add table
- * niceties the grid leaves to the app: cell gridlines, zebra striping, row
- * hover, and a styled pagination bar. Delete any you don't want.
- * ------------------------------------------------------------------------- */
-
-/* Cell gridlines (the grid draws none by default). */
-.sv-grid-column,
-.sv-grid-cell {
-  border-right: 1px solid var(--sg-border) !important;
-  border-bottom: 1px solid var(--sg-border) !important;
-}
-.sv-grid-table tr > :last-child.sv-grid-column,
-.sv-grid-table tr > :last-child.sv-grid-cell {
-  border-right: 0 !important;
-}
-
-/* Zebra striping + row hover. */
-.sv-grid-table tbody tr:nth-child(even) .sv-grid-cell {
-  background: var(--sg-row-alt-bg) !important;
-}
-.sv-grid-table tbody tr:hover .sv-grid-cell {
-  background: var(--sg-row-hover-bg) !important;
-}
-/* Selection wins over zebra (declared after, same specificity). */
-.sv-grid-table tbody tr.sv-grid-row-selected .sv-grid-cell,
-.sv-grid-table tbody tr .sv-grid-cell[data-selected-range='true'] {
-  background: var(--sg-selection-bg) !important;
-}
-
-/* Pagination bar: layout + theme (the grid ships the markup, not the styling). */
-.sv-grid-pagination {
-  display: flex !important;
-  align-items: center !important;
-  justify-content: flex-end !important;
-  gap: 24px !important;
-  padding: 12px 16px !important;
-  border: 1px solid var(--sg-border) !important;
-  border-top: 0 !important;
-  border-radius: 0 0 6px 6px !important;
-  background: var(--sg-header-bg) !important;
-  color: var(--sg-fg) !important;
-  font-size: 13px !important;
-}
-.sv-grid-pagination-pagesize {
-  display: inline-flex;
-  align-items: center;
-  gap: 8px;
-  color: var(--sg-muted);
-}
-.sv-grid-pagination-pagesize select,
-.sv-grid-pagination-btn {
-  border: 1px solid var(--sg-input-border);
-  background: var(--sg-input-bg);
-  color: var(--sg-fg);
-  border-radius: 5px;
-  height: 28px;
-  font: inherit;
-  font-size: 13px;
-  cursor: pointer;
-}
-.sv-grid-pagination-btn {
-  display: inline-flex !important;
-  align-items: center !important;
-  justify-content: center !important;
-  width: 28px !important;
-  border: 0 !important;
-  background: transparent !important;
-  font-size: 16px !important;
-}
-.sv-grid-pagination-btn:hover:not(:disabled) {
-  background: var(--sg-input-bg) !important;
-  color: var(--sg-accent) !important;
-}
-.sv-grid-pagination-btn:disabled {
-  color: var(--sg-muted) !important;
-  opacity: 0.4 !important;
-  cursor: default !important;
-}
-.sv-grid-pagination-nav {
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-}
+@import 'tailwindcss';
+
+/* Tailwind's `dark:` modifier follows the `data-theme` attribute the layout
+ * writes onto <html>, so utility classes and the grid's own --sg-* tokens
+ * switch together. */
+@custom-variant dark (&:where(html[data-theme='dark'], html[data-theme='dark'] *));
+
+/* ---------------------------------------------------------------------------
+ * SvGrid theme tokens - one of @svgrid/grid's 20 built-in presets (pick one
+ * with `npm create @svgrid@latest -- --theme <id> [--dark]`, or edit the
+ * values below by hand). The dashboard shell reads them through the --app-*
+ * aliases further down, so the whole app themes as one, not just the grid.
+ * ------------------------------------------------------------------------- */
+/* svgrid-theme:start */
+:root {
+  --sg-bg: #ffffff;
+  --sg-fg: #0f172a;
+  --sg-muted: #64748b;
+  --sg-border: #e2e8f0;
+  --sg-header-bg: #f8fafc;
+  --sg-header-fg: #0f172a;
+  --sg-bg-subtle: #f8fafc;
+  --sg-row-alt-bg: #ffffff;
+  --sg-row-hover-bg: #f1f5f9;
+  --sg-selection-bg: #e0e7ff;
+  --sg-input-bg: #ffffff;
+  --sg-input-border: #e2e8f0;
+  --sg-accent: #4f46e5;
+  --sg-on-accent: #ffffff;
+  --sg-radius: 6px;
+  --sg-font: Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --sg-scrollbar-bg: #f8fafc;
+  --sg-scrollbar-border: #e2e8f0;
+  --sg-scrollbar-thumb: #64748b;
+  --sg-scrollbar-thumb-hover: #0f172a;
+  --sg-scrollbar-thumb-active: #0f172a;
+  --sg-scrollbar-arrow: #64748b;
+  --sg-scrollbar-arrow-hover: #0f172a;
+  --sg-scrollbar-arrow-hover-bg: #f1f5f9;
+  --sg-scrollbar-arrow-active: #0f172a;
+  --sg-scrollbar-arrow-active-bg: #e0e7ff;
+  --sg-scrollbar-arrow-disabled: #e2e8f0;
+  color-scheme: light;
+}
+:root[data-theme='dark'] {
+  --sg-bg: #0f172a;
+  --sg-fg: #f8fafc;
+  --sg-muted: #94a3b8;
+  --sg-border: #334155;
+  --sg-header-bg: #1e293b;
+  --sg-header-fg: #f8fafc;
+  --sg-bg-subtle: #1e293b;
+  --sg-row-alt-bg: #0f172a;
+  --sg-row-hover-bg: #1e293b;
+  --sg-selection-bg: #312e81;
+  --sg-input-bg: #0f172a;
+  --sg-input-border: #334155;
+  --sg-accent: #818cf8;
+  --sg-on-accent: #18181b;
+  --sg-radius: 6px;
+  --sg-font: Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --sg-scrollbar-bg: #1e293b;
+  --sg-scrollbar-border: #334155;
+  --sg-scrollbar-thumb: #94a3b8;
+  --sg-scrollbar-thumb-hover: #f8fafc;
+  --sg-scrollbar-thumb-active: #f8fafc;
+  --sg-scrollbar-arrow: #94a3b8;
+  --sg-scrollbar-arrow-hover: #f8fafc;
+  --sg-scrollbar-arrow-hover-bg: #1e293b;
+  --sg-scrollbar-arrow-active: #f8fafc;
+  --sg-scrollbar-arrow-active-bg: #312e81;
+  --sg-scrollbar-arrow-disabled: #334155;
+  color-scheme: dark;
+}
+/* svgrid-theme:end */
+
+/* Dashboard shell aliases - map the chrome to the grid tokens above, so any
+ * theme (light or dark, whichever preset) reskins the whole page as one. */
+:root {
+  --app-bg: var(--sg-row-alt-bg);
+  --app-panel: var(--sg-bg);
+  --app-border: var(--sg-border);
+  --app-fg: var(--sg-fg);
+  --app-muted: var(--sg-muted);
+  --app-accent: var(--sg-accent);
+  /* Text that sits ON the accent. Every preset declares this, and it is NOT
+     always white: shadcn dark uses a near-white accent (#fafafa) with near-black
+     text. Hardcoding #fff here made the active nav item invisible. */
+  --app-on-accent: var(--sg-on-accent);
+}
+
+html,
+body {
+  background: var(--app-bg);
+  color: var(--app-fg);
+  font-family: var(--sg-font, Inter, ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial,
+    sans-serif);
+}
+
+/* ---------------------------------------------------------------------------
+ * Optional polish. The grid themes itself from the --sg-* tokens above, so it
+ * already follows light / dark with no extra CSS. These rules only add table
+ * niceties the grid leaves to the app: cell gridlines, zebra striping, row
+ * hover, and a styled pagination bar. Delete any you don't want.
+ * ------------------------------------------------------------------------- */
+
+/* Cell gridlines (the grid draws none by default). */
+.sv-grid-column,
+.sv-grid-cell {
+  border-right: 1px solid var(--sg-border) !important;
+  border-bottom: 1px solid var(--sg-border) !important;
+}
+.sv-grid-table tr > :last-child.sv-grid-column,
+.sv-grid-table tr > :last-child.sv-grid-cell {
+  border-right: 0 !important;
+}
+
+/* Zebra striping + row hover. */
+.sv-grid-table tbody tr:nth-child(even) .sv-grid-cell {
+  background: var(--sg-row-alt-bg) !important;
+}
+.sv-grid-table tbody tr:hover .sv-grid-cell {
+  background: var(--sg-row-hover-bg) !important;
+}
+/* Selection wins over zebra (declared after, same specificity). */
+.sv-grid-table tbody tr.sv-grid-row-selected .sv-grid-cell,
+.sv-grid-table tbody tr .sv-grid-cell[data-selected-range='true'] {
+  background: var(--sg-selection-bg) !important;
+}
+
+/* Pagination bar: layout + theme (the grid ships the markup, not the styling). */
+.sv-grid-pagination {
+  display: flex !important;
+  align-items: center !important;
+  justify-content: flex-end !important;
+  gap: 24px !important;
+  padding: 12px 16px !important;
+  border: 1px solid var(--sg-border) !important;
+  border-top: 0 !important;
+  border-radius: 0 0 6px 6px !important;
+  background: var(--sg-header-bg) !important;
+  color: var(--sg-fg) !important;
+  font-size: 13px !important;
+}
+.sv-grid-pagination-pagesize {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--sg-muted);
+}
+.sv-grid-pagination-pagesize select,
+.sv-grid-pagination-btn {
+  border: 1px solid var(--sg-input-border);
+  background: var(--sg-input-bg);
+  color: var(--sg-fg);
+  border-radius: 5px;
+  height: 28px;
+  font: inherit;
+  font-size: 13px;
+  cursor: pointer;
+}
+.sv-grid-pagination-btn {
+  display: inline-flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+  width: 28px !important;
+  border: 0 !important;
+  background: transparent !important;
+  font-size: 16px !important;
+}
+.sv-grid-pagination-btn:hover:not(:disabled) {
+  background: var(--sg-input-bg) !important;
+  color: var(--sg-accent) !important;
+}
+.sv-grid-pagination-btn:disabled {
+  color: var(--sg-muted) !important;
+  opacity: 0.4 !important;
+  cursor: default !important;
+}
+.sv-grid-pagination-nav {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}

package/templates/sveltekit/README.md

@@ -0,0 +1,44 @@
+# SvGrid + SvelteKit sample
+
+A grid whose rows are loaded on the server, sorted from the URL, and edited
+through a form action - the three things that are different about running a grid
+in SvelteKit rather than a plain Vite SPA.
+
+```bash
+npm install
+npm run dev     # http://localhost:5173/people
+```
+
+## What to try
+
+1. **Click the `Year` header.** The URL becomes `?sort=year&dir=asc`. Copy that
+   link into a new tab - it opens already sorted, because the server did it.
+2. **Double-click a name, change it, press Enter, then reload.** The edit went
+   through the form action in `+page.server.ts` and survived.
+3. **Switch the theme** with the picker in the header. All 20 built-in presets,
+   light and dark, applied live.
+4. **`curl localhost:5173/people`.** The rows are in the HTML, not injected by
+   JS afterwards. That is what a crawler sees.
+
+## Where things are
+
+| File | Does |
+| --- | --- |
+| `src/lib/people.ts` | Stands in for your database. Swap for real queries. |
+| `src/routes/people/+page.server.ts` | `load` sorts from the query string; the `rename` action takes the edit. |
+| `src/routes/people/+page.svelte` | The grid. `externalSort` because the server owns the ordering. |
+| `src/lib/theme.svelte.ts` | Runtime theme switching via `resolveThemeTokens`. |
+| `src/app.css` | Imports one preset so the first paint is themed before JS runs. |
+
+## Themes
+
+Pick a starting theme when you scaffold:
+
+```bash
+npm create @svgrid@latest my-app -- --template sveltekit --theme dracula --dark
+```
+
+Or change it at runtime with the header picker. The picker writes the preset's
+`--sg-*` custom properties onto `<html>`; nothing rebuilds.
+
+Full guide: https://svgrid.com/docs/getting-started/sveltekit/

package/templates/sveltekit/_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/sveltekit/_package.json

@@ -0,0 +1,26 @@
+{
+  "name": "svgrid-sveltekit-sample",
+  "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"
+  }
+}

package/templates/sveltekit/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/tailwind.css';
+/* svgrid-theme:end */
+
+* { box-sizing: border-box; }
+body { margin: 0; }

package/templates/sveltekit/src/app.d.ts

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

package/templates/sveltekit/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/sveltekit/src/lib/people.ts

@@ -0,0 +1,22 @@
+export type Person = { id: number; name: string; role: string; year: number }
+
+// Stands in for your database. Mutating a module-level array is fine for a
+// tutorial; swap it for real queries and the rest of the page is unchanged.
+const people: Person[] = [
+  { id: 1, name: 'Ada Lovelace', role: 'Mathematician', year: 1843 },
+  { id: 2, name: 'Grace Hopper', role: 'Rear Admiral', year: 1952 },
+  { id: 3, name: 'Karen Sparck Jones', role: 'Computer Scientist', year: 1972 },
+  { id: 4, name: 'Barbara Liskov', role: 'Computer Scientist', year: 1968 },
+  { id: 5, name: 'Margaret Hamilton', role: 'Software Engineer', year: 1969 },
+]
+
+export function listPeople(sortBy: keyof Person = 'name', desc = false): Person[] {
+  const rows = [...people]
+  rows.sort((a, b) => (a[sortBy] > b[sortBy] ? 1 : a[sortBy] < b[sortBy] ? -1 : 0))
+  return desc ? rows.reverse() : rows
+}
+
+export function renamePerson(id: number, name: string): void {
+  const row = people.find((p) => p.id === id)
+  if (row) row.name = name
+}

package/templates/sveltekit/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 = 'tailwind'
+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/sveltekit/src/routes/+layout.svelte

@@ -0,0 +1,78 @@
+<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>SvGrid + SvelteKit</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/sveltekit/src/routes/+page.svelte

@@ -0,0 +1,7 @@
+<h1>SvGrid + SvelteKit</h1>
+<p>
+  The sample lives at <a href="/people">/people</a> - a grid whose rows are
+  loaded in <code>+page.server.ts</code>, sorted from the URL, and edited through
+  a form action.
+</p>
+<p>Use the picker in the header to switch the grid theme while it runs.</p>

package/templates/sveltekit/src/routes/people/+page.server.ts

@@ -0,0 +1,16 @@
+import type { Actions, PageServerLoad } from './$types'
+import { listPeople, renamePerson, type Person } from '$lib/people'
+
+export const load: PageServerLoad = ({ url }) => {
+  const sortBy = (url.searchParams.get('sort') ?? 'name') as keyof Person
+  const desc = url.searchParams.get('dir') === 'desc'
+  return { rows: listPeople(sortBy, desc), sortBy, desc }
+}
+
+export const actions: Actions = {
+  rename: async ({ request }) => {
+    const data = await request.formData()
+    renamePerson(Number(data.get('id')), String(data.get('name')))
+    return { success: true }
+  },
+}

package/templates/sveltekit/src/routes/people/+page.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+  import { goto } from '$app/navigation'
+  import { page } from '$app/state'
+  import { SvGrid, type GridColumns } from '@svgrid/grid'
+  import type { Person } from '$lib/people'
+
+  let { data } = $props()
+
+  const columns: GridColumns<Person> = [
+    { field: 'name', header: 'Name', editable: true },
+    { field: 'role', header: 'Role' },
+    { field: 'year', header: 'Year' },
+  ]
+
+  // Header click -> URL -> server sorts -> load returns ordered rows.
+  function onSortingChange(sorting: Array<{ id: string; desc: boolean }>) {
+    const next = new URL(page.url)
+    if (sorting.length === 0) {
+      next.searchParams.delete('sort')
+      next.searchParams.delete('dir')
+    } else {
+      next.searchParams.set('sort', sorting[0]!.id)
+      next.searchParams.set('dir', sorting[0]!.desc ? 'desc' : 'asc')
+    }
+    goto(next, { keepFocus: true, noScroll: true })
+  }
+
+  // Committed edit -> form action -> database.
+  async function onCellValueChange(e: { row: Person; columnId: string; newValue: unknown }) {
+    if (e.columnId !== 'name') return
+    const body = new FormData()
+    body.set('id', String(e.row.id))
+    body.set('name', String(e.newValue))
+    await fetch('?/rename', { method: 'POST', body })
+  }
+</script>
+
+<h1>People</h1>
+<p>Click a header to sort - the order lives in the URL. Double-click a name to edit it.</p>
+
+<SvGrid
+  data={data.rows}
+  {columns}
+  sortable
+  editable
+  externalSort
+  initialSorting={[{ id: data.sortBy, desc: data.desc }]}
+  {onSortingChange}
+  {onCellValueChange}
+  containerHeight={320}
+/>

package/templates/sveltekit/tsconfig.json

@@ -0,0 +1,20 @@
+{
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"rewriteRelativeImportExtensions": true,
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"moduleResolution": "bundler"
+	}
+	// Path aliases are handled by https://svelte.dev/docs/kit/configuration#alias
+	// except $lib which is handled by https://svelte.dev/docs/kit/configuration#files
+	//
+	// To make changes to top-level options such as include and exclude, we recommend extending
+	// the generated config; see https://svelte.dev/docs/kit/configuration#typescript
+}

package/templates/sveltekit/vite.config.ts

@@ -0,0 +1,20 @@
+import adapter from '@sveltejs/adapter-auto';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [
+		sveltekit({
+			compilerOptions: {
+				// Force runes mode for the project, except for libraries. Can be removed in svelte 6.
+				runes: ({ filename }) =>
+					filename.split(/[/\\]/).includes('node_modules') ? undefined : true
+			},
+
+			// adapter-auto only supports some environments, see https://svelte.dev/docs/kit/adapter-auto for a list.
+			// If your environment is not supported, or you settled on a specific environment, switch out the adapter.
+			// See https://svelte.dev/docs/kit/adapters for more information about adapters.
+			adapter: adapter()
+		})
+	]
+});